orb-billing 1.21.0 → 1.23.0

package/src/index.ts

@@ -0,0 +1,305 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from './core';
+import * as Pagination from './pagination';
+import * as Errors from './error';
+import { type Agent } from './_shims/index';
+import * as Uploads from './uploads';
+import * as API from "./resources/index";
+
+export interface ClientOptions {
+  /**
+   * Defaults to process.env['ORB_API_KEY'].
+   */
+  apiKey?: string;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   */
+  baseURL?: string;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
+  timeout?: number;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
+  httpAgent?: Agent;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+   * defined globally.
+   */
+  fetch?: Core.Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 2
+   */
+  maxRetries?: number;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
+  defaultHeaders?: Core.Headers;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Core.DefaultQuery;
+}
+
+/** API Client for interfacing with the Orb API. */
+export class Orb extends Core.APIClient {
+  apiKey: string;
+
+  private _options: ClientOptions;
+
+  /**
+   * API Client for interfacing with the Orb API.
+   *
+   * @param {string} [opts.apiKey==process.env['ORB_API_KEY'] ?? undefined]
+   * @param {string} [opts.baseURL] - 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.
+   * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+   * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+   */
+  constructor({ apiKey = Core.readEnv('ORB_API_KEY'), ...opts }: ClientOptions = {}) {
+    if (apiKey === undefined) {
+      throw new Errors.OrbError(
+        "The ORB_API_KEY environment variable is missing or empty; either provide it, or instantiate the Orb client with an apiKey option, like new Orb({ apiKey: 'My API Key' }).",
+      );
+    }
+
+    const options: ClientOptions = {
+      apiKey,
+      ...opts,
+      baseURL: opts.baseURL ?? `https://api.withorb.com/v1`,
+    };
+
+    super({
+      baseURL: options.baseURL!,
+      timeout: options.timeout ?? 60000 /* 1 minute */,
+      httpAgent: options.httpAgent,
+      maxRetries: options.maxRetries,
+      fetch: options.fetch,
+    });
+    this._options = options;
+    this.idempotencyHeader = 'Idempotency-Key';
+
+    this.apiKey = apiKey;
+  }
+
+  topLevel: API.TopLevel = new API.TopLevel(this);
+  coupons: API.Coupons = new API.Coupons(this);
+  creditNotes: API.CreditNotes = new API.CreditNotes(this);
+  customers: API.Customers = new API.Customers(this);
+  events: API.Events = new API.Events(this);
+  invoiceLineItems: API.InvoiceLineItems = new API.InvoiceLineItems(this);
+  invoices: API.Invoices = new API.Invoices(this);
+  items: API.Items = new API.Items(this);
+  metrics: API.Metrics = new API.Metrics(this);
+  plans: API.Plans = new API.Plans(this);
+  prices: API.Prices = new API.Prices(this);
+  subscriptions: API.Subscriptions = new API.Subscriptions(this);
+
+  protected override defaultQuery(): Core.DefaultQuery | undefined {
+    return this._options.defaultQuery;
+  }
+
+  protected override defaultHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return {
+      ...super.defaultHeaders(opts),
+      ...this._options.defaultHeaders,
+    };
+  }
+
+  protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return { Authorization: `Bearer ${this.apiKey}` };
+  }
+
+  static Orb = this;
+
+  static OrbError = Errors.OrbError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
+  static URLNotFound = Errors.URLNotFound;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static BadRequestError = Errors.BadRequestError;
+  static RequestTooLarge = Errors.RequestTooLarge;
+  static TooManyRequests = Errors.TooManyRequests;
+  static ResourceNotFound = Errors.ResourceNotFound;
+  static ResourceConflict = Errors.ResourceConflict;
+  static ResourceTooLarge = Errors.ResourceTooLarge;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static FeatureNotAvailable = Errors.FeatureNotAvailable;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static OrbAuthenticationError = Errors.OrbAuthenticationError;
+  static OrbInternalServerError = Errors.OrbInternalServerError;
+  static RequestValidationErrors = Errors.RequestValidationErrors;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
+  static DuplicateResourceCreation = Errors.DuplicateResourceCreation;
+}
+
+export const {
+  OrbError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+  URLNotFound,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  BadRequestError,
+  RequestTooLarge,
+  TooManyRequests,
+  ResourceNotFound,
+  ResourceConflict,
+  ResourceTooLarge,
+  AuthenticationError,
+  InternalServerError,
+  FeatureNotAvailable,
+  PermissionDeniedError,
+  OrbAuthenticationError,
+  OrbInternalServerError,
+  RequestValidationErrors,
+  UnprocessableEntityError,
+  DuplicateResourceCreation,
+} = Errors;
+
+export import toFile = Uploads.toFile;
+export import fileFromPath = Uploads.fileFromPath;
+
+export namespace Orb {
+  // Helper functions
+  export import toFile = Uploads.toFile;
+  export import fileFromPath = Uploads.fileFromPath;
+
+  export import RequestOptions = Core.RequestOptions;
+
+  export import Page = Pagination.Page;
+  export import PageParams = Pagination.PageParams;
+  export import PageResponse = Pagination.PageResponse;
+
+  export import TopLevel = API.TopLevel;
+  export import TopLevelPingResponse = API.TopLevelPingResponse;
+
+  export import Coupons = API.Coupons;
+  export import Coupon = API.Coupon;
+  export import CouponsPage = API.CouponsPage;
+  export import CouponCreateParams = API.CouponCreateParams;
+  export import CouponListParams = API.CouponListParams;
+
+  export import CreditNotes = API.CreditNotes;
+  export import CreditNote = API.CreditNote;
+  export import CreditNotesPage = API.CreditNotesPage;
+  export import CreditNoteListParams = API.CreditNoteListParams;
+
+  export import Customers = API.Customers;
+  export import Customer = API.Customer;
+  export import CustomersPage = API.CustomersPage;
+  export import CustomerCreateParams = API.CustomerCreateParams;
+  export import CustomerUpdateParams = API.CustomerUpdateParams;
+  export import CustomerListParams = API.CustomerListParams;
+  export import CustomerUpdateByExternalIDParams = API.CustomerUpdateByExternalIDParams;
+
+  export import Events = API.Events;
+  export import EventUpdateResponse = API.EventUpdateResponse;
+  export import EventDeprecateResponse = API.EventDeprecateResponse;
+  export import EventIngestResponse = API.EventIngestResponse;
+  export import EventSearchResponse = API.EventSearchResponse;
+  export import EventUpdateParams = API.EventUpdateParams;
+  export import EventIngestParams = API.EventIngestParams;
+  export import EventSearchParams = API.EventSearchParams;
+
+  export import InvoiceLineItems = API.InvoiceLineItems;
+  export import InvoiceLineItemCreateResponse = API.InvoiceLineItemCreateResponse;
+  export import InvoiceLineItemCreateParams = API.InvoiceLineItemCreateParams;
+
+  export import Invoices = API.Invoices;
+  export import Invoice = API.Invoice;
+  export import InvoiceDiscount = API.InvoiceDiscount;
+  export import InvoiceFetchUpcomingResponse = API.InvoiceFetchUpcomingResponse;
+  export import InvoicesPage = API.InvoicesPage;
+  export import InvoiceCreateParams = API.InvoiceCreateParams;
+  export import InvoiceListParams = API.InvoiceListParams;
+  export import InvoiceFetchUpcomingParams = API.InvoiceFetchUpcomingParams;
+  export import InvoiceMarkPaidParams = API.InvoiceMarkPaidParams;
+
+  export import Items = API.Items;
+  export import ItemListResponse = API.ItemListResponse;
+  export import ItemFetchResponse = API.ItemFetchResponse;
+  export import ItemListResponsesPage = API.ItemListResponsesPage;
+  export import ItemListParams = API.ItemListParams;
+
+  export import Metrics = API.Metrics;
+  export import MetricCreateResponse = API.MetricCreateResponse;
+  export import MetricListResponse = API.MetricListResponse;
+  export import MetricFetchResponse = API.MetricFetchResponse;
+  export import MetricListResponsesPage = API.MetricListResponsesPage;
+  export import MetricCreateParams = API.MetricCreateParams;
+  export import MetricListParams = API.MetricListParams;
+
+  export import Plans = API.Plans;
+  export import Plan = API.Plan;
+  export import PlansPage = API.PlansPage;
+  export import PlanCreateParams = API.PlanCreateParams;
+  export import PlanUpdateParams = API.PlanUpdateParams;
+  export import PlanListParams = API.PlanListParams;
+
+  export import Prices = API.Prices;
+  export import Discount = API.Discount;
+  export import Price = API.Price;
+  export import PricesPage = API.PricesPage;
+  export import PriceCreateParams = API.PriceCreateParams;
+  export import PriceListParams = API.PriceListParams;
+
+  export import Subscriptions = API.Subscriptions;
+  export import Subscription = API.Subscription;
+  export import SubscriptionUsage = API.SubscriptionUsage;
+  export import SubscriptionFetchCostsResponse = API.SubscriptionFetchCostsResponse;
+  export import SubscriptionFetchScheduleResponse = API.SubscriptionFetchScheduleResponse;
+  export import SubscriptionsPage = API.SubscriptionsPage;
+  export import SubscriptionFetchScheduleResponsesPage = API.SubscriptionFetchScheduleResponsesPage;
+  export import SubscriptionCreateParams = API.SubscriptionCreateParams;
+  export import SubscriptionListParams = API.SubscriptionListParams;
+  export import SubscriptionCancelParams = API.SubscriptionCancelParams;
+  export import SubscriptionFetchCostsParams = API.SubscriptionFetchCostsParams;
+  export import SubscriptionFetchScheduleParams = API.SubscriptionFetchScheduleParams;
+  export import SubscriptionFetchUsageParams = API.SubscriptionFetchUsageParams;
+  export import SubscriptionPriceIntervalsParams = API.SubscriptionPriceIntervalsParams;
+  export import SubscriptionSchedulePlanChangeParams = API.SubscriptionSchedulePlanChangeParams;
+  export import SubscriptionTriggerPhaseParams = API.SubscriptionTriggerPhaseParams;
+  export import SubscriptionUnscheduleFixedFeeQuantityUpdatesParams = API.SubscriptionUnscheduleFixedFeeQuantityUpdatesParams;
+  export import SubscriptionUpdateFixedFeeQuantityParams = API.SubscriptionUpdateFixedFeeQuantityParams;
+}
+
+export default Orb;

package/src/pagination.ts

@@ -0,0 +1,63 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
+
+export interface PageResponse<Item> {
+  data: Array<Item>;
+
+  pagination_metadata: PageResponse.PaginationMetadata;
+}
+
+export namespace PageResponse {
+  export interface PaginationMetadata {
+    has_more: boolean;
+
+    next_cursor: string | null;
+  }
+}
+
+export interface PageParams {
+  /**
+   * Cursor for pagination. This can be populated by the `next_cursor` value returned
+   * from the initial request.
+   */
+  cursor?: string | null;
+
+  /**
+   * The number of items to fetch. Defaults to 20.
+   */
+  limit?: number;
+}
+
+export class Page<Item> extends AbstractPage<Item> implements PageResponse<Item> {
+  data: Array<Item>;
+
+  pagination_metadata: PageResponse.PaginationMetadata;
+
+  constructor(client: APIClient, response: Response, body: PageResponse<Item>, options: FinalRequestOptions) {
+    super(client, response, body, options);
+
+    this.data = body.data;
+    this.pagination_metadata = body.pagination_metadata;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data;
+  }
+
+  // @deprecated Please use `nextPageInfo()` instead
+  nextPageParams(): Partial<PageParams> | null {
+    const info = this.nextPageInfo();
+    if (!info) return null;
+    if ('params' in info) return info.params;
+    const params = Object.fromEntries(info.url.searchParams);
+    if (!Object.keys(params).length) return null;
+    return params;
+  }
+
+  nextPageInfo(): PageInfo | null {
+    if (!this.pagination_metadata.next_cursor) return null;
+
+    return { params: { cursor: this.pagination_metadata.next_cursor } };
+  }
+}

package/src/resource.ts

@@ -0,0 +1,24 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import type { Orb } from './index';
+
+export class APIResource {
+  protected client: Orb;
+  constructor(client: Orb) {
+    this.client = client;
+
+    this.get = client.get.bind(client);
+    this.post = client.post.bind(client);
+    this.patch = client.patch.bind(client);
+    this.put = client.put.bind(client);
+    this.delete = client.delete.bind(client);
+    this.getAPIList = client.getAPIList.bind(client);
+  }
+
+  protected get: Orb['get'];
+  protected post: Orb['post'];
+  protected patch: Orb['patch'];
+  protected put: Orb['put'];
+  protected delete: Orb['delete'];
+  protected getAPIList: Orb['getAPIList'];
+}

package/src/resources/coupons/coupons.ts

@@ -0,0 +1,150 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../../core";
+import { APIResource } from "../../resource";
+import { isRequestOptions } from "../../core";
+import * as CouponsAPI from "./coupons";
+import * as SubscriptionsAPI from "./subscriptions";
+import { Page, type PageParams } from "../../pagination";
+
+export class Coupons extends APIResource {
+  subscriptions: SubscriptionsAPI.Subscriptions = new SubscriptionsAPI.Subscriptions(this.client);
+
+  /**
+   * This endpoint allows the creation of coupons, which can then be redeemed at
+   * subscription creation or plan change.
+   */
+  create(body: CouponCreateParams, options?: Core.RequestOptions): Core.APIPromise<Coupon> {
+    return this.post('/coupons', { body, ...options });
+  }
+
+  /**
+   * This endpoint returns a list of all coupons for an account in a list format.
+   *
+   * The list of coupons is ordered starting from the most recently created coupon.
+   * The response also includes `pagination_metadata`, which lets the caller retrieve
+   * the next page of results if they exist. More information about pagination can be
+   * found in the Pagination-metadata schema.
+   */
+  list(query?: CouponListParams, options?: Core.RequestOptions): Core.PagePromise<CouponsPage, Coupon>;
+  list(options?: Core.RequestOptions): Core.PagePromise<CouponsPage, Coupon>;
+  list(
+    query: CouponListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<CouponsPage, Coupon> {
+    if (isRequestOptions(query)) {
+      return this.list({}, query);
+    }
+    return this.getAPIList('/coupons', CouponsPage, { query, ...options });
+  }
+
+  /**
+   * This endpoint allows a coupon to be archived. Archived coupons can no longer be
+   * redeemed, and will be hidden from lists of active coupons. Additionally, once a
+   * coupon is archived, its redemption code can be reused for a different coupon.
+   */
+  archive(couponId: string, options?: Core.RequestOptions): Core.APIPromise<Coupon> {
+    return this.post(`/coupons/${couponId}/archive`, options);
+  }
+
+  /**
+   * This endpoint retrieves a coupon by its ID. To fetch coupons by their redemption
+   * code, use the [List coupons](list-coupons) endpoint with the redemption_code
+   * parameter.
+   */
+  fetch(couponId: string, options?: Core.RequestOptions): Core.APIPromise<Coupon> {
+    return this.get(`/coupons/${couponId}`, options);
+  }
+}
+
+export class CouponsPage extends Page<Coupon> {}
+
+/**
+ * A coupon represents a reusable discount configuration, and have an attached
+ * redemption code that can be issued to your end users. Coupons are most often
+ * used in self-serve signup or upgrade flows in your checkout experience or
+ * billing portal.
+ *
+ * To redeem a coupon, pass the `redemption_code` property in the
+ * [create subscription](create-subscription.api.mdx) or
+ * [schedule plan change](schedule-plan-change.api.mdx) request.
+ */
+export interface Coupon {
+  /**
+   * Also referred to as coupon_id in this documentation.
+   */
+  id: string;
+
+  /**
+   * An archived coupon can no longer be redeemed. Active coupons will have a value
+   * of null for `archived_at`; this field will be non-null for archived coupons.
+   */
+  archived_at: string | null;
+
+  discount: unknown;
+
+  /**
+   * This allows for a coupon's discount to apply for a limited time (determined in
+   * months); a `null` value here means "unlimited time".
+   */
+  duration_in_months: number | null;
+
+  /**
+   * The maximum number of redemptions allowed for this coupon before it is
+   * exhausted; `null` here means "unlimited".
+   */
+  max_redemptions: number | null;
+
+  /**
+   * This string can be used to redeem this coupon for a given subscription.
+   */
+  redemption_code: string;
+
+  /**
+   * The number of times this coupon has been redeemed.
+   */
+  times_redeemed: number;
+}
+
+export interface CouponCreateParams {
+  discount: unknown;
+
+  /**
+   * This string can be used to redeem this coupon for a given subscription.
+   */
+  redemption_code: string;
+
+  /**
+   * This allows for a coupon's discount to apply for a limited time (determined in
+   * months); a `null` value here means "unlimited time".
+   */
+  duration_in_months?: number | null;
+
+  /**
+   * The maximum number of redemptions allowed for this coupon before it is
+   * exhausted;`null` here means "unlimited".
+   */
+  max_redemptions?: number | null;
+}
+
+export interface CouponListParams extends PageParams {
+  /**
+   * Filter to coupons matching this redemption code.
+   */
+  redemption_code?: string | null;
+
+  /**
+   * Show archived coupons as well (by default, this endpoint only returns active
+   * coupons).
+   */
+  show_archived?: boolean | null;
+}
+
+export namespace Coupons {
+  export import Coupon = CouponsAPI.Coupon;
+  export import CouponsPage = CouponsAPI.CouponsPage;
+  export import CouponCreateParams = CouponsAPI.CouponCreateParams;
+  export import CouponListParams = CouponsAPI.CouponListParams;
+  export import Subscriptions = SubscriptionsAPI.Subscriptions;
+  export import SubscriptionListParams = SubscriptionsAPI.SubscriptionListParams;
+}

package/src/resources/coupons/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless.
+
+export { Coupon, CouponCreateParams, CouponListParams, CouponsPage, Coupons } from './coupons';
+export { SubscriptionListParams, Subscriptions } from './subscriptions';

package/src/resources/coupons/subscriptions.ts

@@ -0,0 +1,45 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from "../../core";
+import { APIResource } from "../../resource";
+import { isRequestOptions } from "../../core";
+import * as CouponsSubscriptionsAPI from "./subscriptions";
+import * as SubscriptionsAPI from "../subscriptions";
+import { SubscriptionsPage } from "../subscriptions";
+import { type PageParams } from "../../pagination";
+
+export class Subscriptions extends APIResource {
+  /**
+   * This endpoint returns a list of all subscriptions that have redeemed a given
+   * coupon as a [paginated](../reference/pagination) list, ordered starting from the
+   * most recently created subscription. For a full discussion of the subscription
+   * resource, see [Subscription](../guides/concepts#subscription).
+   */
+  list(
+    couponId: string,
+    query?: SubscriptionListParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<SubscriptionsPage, SubscriptionsAPI.Subscription>;
+  list(
+    couponId: string,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<SubscriptionsPage, SubscriptionsAPI.Subscription>;
+  list(
+    couponId: string,
+    query: SubscriptionListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<SubscriptionsPage, SubscriptionsAPI.Subscription> {
+    if (isRequestOptions(query)) {
+      return this.list(couponId, {}, query);
+    }
+    return this.getAPIList(`/coupons/${couponId}/subscriptions`, SubscriptionsPage, { query, ...options });
+  }
+}
+
+export interface SubscriptionListParams extends PageParams {}
+
+export namespace Subscriptions {
+  export import SubscriptionListParams = CouponsSubscriptionsAPI.SubscriptionListParams;
+}
+
+export { SubscriptionsPage };