orb-billing 1.19.2 → 1.20.0

package/README.md

@@ -20,21 +20,80 @@ yarn add orb-billing
 <!-- Start SDK Example Usage -->
 ```typescript
 import { Orb } from "orb-billing";
-import { PingResponse } from "orb-billing/dist/sdk/models/operations";
 
+(async() => {
+  const sdk = new Orb({
+    security: {
+      apiKeyAuth: "",
+    },
+  });
+
+  const res = await sdk.availability.ping();
+
+  if (res.statusCode == 200) {
+    // handle response
+  }
+})();
+```
+<!-- End SDK Example Usage -->
+
+<!-- Start Pagination -->
+# Pagination
+
+Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the
+returned response object will have a `next` method that can be called to pull down the next group of results. If the
+return value of `next` is `null`, then there are no more pages to be fetched.
+
+Here's an example of one such pagination call:
+<!-- End Pagination -->
+
+```ts
+/* eslint-disable prefer-const */
+import { Orb } from "orb-billing";
+
+// Initialize the SDK with an API key.
 const sdk = new Orb({
   security: {
     apiKeyAuth: "",
   },
 });
 
-sdk.availability.ping().then((res: PingResponse) => {
-  if (res.statusCode == 200) {
-    // handle response
-  }
-});
+async function paginationDemo() {
+  let cursor: string | undefined;
+
+  // We start by attempting to fetch at least one page of results.
+  do {
+    // The SDK call takes the cursor and any additional arguments to filter the
+    // coupon data.
+    const response = await sdk.coupon.list({ cursor, showArchived: false });
+    const { statusCode } = response;
+    if (statusCode !== 200) {
+      throw new Error(`Unexpected status code sent from server: ${statusCode}`);
+    }
+
+    // We capture the cursor for the next iteration but we also check if we
+    // received an empty page of results as a signal to stop making additional
+    // requests.
+    cursor = response.coupons?.paginationMetadata.nextCursor;
+    const page = response.coupons?.data;
+    if (!page?.length) {
+      break;
+    }
+
+    // At this point we have a page of coupon entries that we can collect or
+    // iterate through as shown below.
+    page.forEach((coupon) => {
+      const { redemptionCode: code, timesRedeemed } = coupon;
+      console.log(`Coupon ${code} was redeemed ${timesRedeemed} times.`);
+    });
+
+    // The loop will continue if we received a cursor for additional results.
+  } while (cursor);
+}
+
+// Run the demo function.
+paginationDemo();
 ```
-<!-- End SDK Example Usage -->
 
 <!-- Start SDK Available Operations -->
 ## Available Resources and Operations
@@ -153,28 +212,12 @@ sdk.availability.ping().then((res: PingResponse) => {
 * [updateFixedFeeQuantity](docs/sdks/subscription/README.md#updatefixedfeequantity) - Update price quantity
 <!-- End SDK Available Operations -->
 
-
-
 <!-- Start Dev Containers -->
 
 <!-- End Dev Containers -->
 
-
-
-<!-- Start Pagination -->
-# Pagination
-
-Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the
-returned response object will have a `next` method that can be called to pull down the next group of results. If the
-return value of `next` is `null`, then there are no more pages to be fetched.
-
-Here's an example of one such pagination call:
-<!-- End Pagination -->
-
 <!-- Placeholder for Future Speakeasy SDK Sections -->
 
-
-
 ### Maturity
 
 This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage

package/dist/internal/utils/utils.js

@@ -104,7 +104,7 @@ var SpeakeasyBase = /** @class */ (function () {
                     var prop = props_1_1.value;
                     if (payload && payload.hasOwnProperty(prop.key)) {
                         var value = payload[prop.key];
-                        if (isSpeakeasyBase(prop.type)) {
+                        if (isSpeakeasyBase(prop.type) && value != null) {
                             this[prop.key] = new prop.type(value);
                         }
                         else if (prop.type.name == "Array" &&

package/dist/sdk/coupon.d.ts

@@ -23,7 +23,7 @@ export declare class Coupon {
      * 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(req: operations.ArchiveCouponRequest, config?: AxiosRequestConfig): Promise<operations.ArchiveCouponResponse>;
+    archive(couponId: string, config?: AxiosRequestConfig): Promise<operations.ArchiveCouponResponse>;
     /**
      * Create coupon
      *
@@ -38,7 +38,7 @@ export declare class Coupon {
      * 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(req: operations.FetchCouponRequest, config?: AxiosRequestConfig): Promise<operations.FetchCouponResponse>;
+    fetch(couponId: string, config?: AxiosRequestConfig): Promise<operations.FetchCouponResponse>;
     /**
      * List coupons
      *
@@ -49,7 +49,7 @@ export declare class Coupon {
      * `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(req: operations.ListCouponsRequest, config?: AxiosRequestConfig): Promise<operations.ListCouponsResponse>;
+    list(cursor?: string, limit?: number, redemptionCode?: string, showArchived?: boolean, config?: AxiosRequestConfig): Promise<operations.ListCouponsResponse>;
     /**
      * List coupon subscriptions
      *
@@ -58,5 +58,5 @@ export declare class Coupon {
      * [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).
      */
-    listSubscriptions(req: operations.ListCouponSubscriptionsRequest, config?: AxiosRequestConfig): Promise<operations.ListCouponSubscriptionsResponse>;
+    listSubscriptions(couponId: string, cursor?: string, limit?: number, config?: AxiosRequestConfig): Promise<operations.ListCouponSubscriptionsResponse>;
 }

package/dist/sdk/coupon.js

@@ -116,16 +116,16 @@ var Coupon = /** @class */ (function () {
      * will be hidden from lists of active coupons. Additionally, once a coupon is archived, its redemption
      * code can be reused for a different coupon.
      */
-    Coupon.prototype.archive = function (req, config) {
+    Coupon.prototype.archive = function (couponId, config) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function () {
-            var baseURL, url, client, globalSecurity, properties, headers, httpRes, contentType, res, decodedRes;
+            var req, baseURL, url, client, globalSecurity, properties, headers, httpRes, contentType, res, decodedRes;
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
-                        if (!(req instanceof utils.SpeakeasyBase)) {
-                            req = new operations.ArchiveCouponRequest(req);
-                        }
+                        req = new operations.ArchiveCouponRequest({
+                            couponId: couponId,
+                        });
                         baseURL = utils.templateUrl(this.sdkConfiguration.serverURL, this.sdkConfiguration.serverDefaults);
                         url = utils.generateURL(baseURL, "/coupons/{coupon_id}/archive", req);
                         client = this.sdkConfiguration.defaultClient;
@@ -361,16 +361,16 @@ var Coupon = /** @class */ (function () {
      * 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.
      */
-    Coupon.prototype.fetch = function (req, config) {
+    Coupon.prototype.fetch = function (couponId, config) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function () {
-            var baseURL, url, client, globalSecurity, properties, headers, httpRes, contentType, res, decodedRes;
+            var req, baseURL, url, client, globalSecurity, properties, headers, httpRes, contentType, res, decodedRes;
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
-                        if (!(req instanceof utils.SpeakeasyBase)) {
-                            req = new operations.FetchCouponRequest(req);
-                        }
+                        req = new operations.FetchCouponRequest({
+                            couponId: couponId,
+                        });
                         baseURL = utils.templateUrl(this.sdkConfiguration.serverURL, this.sdkConfiguration.serverDefaults);
                         url = utils.generateURL(baseURL, "/coupons/{coupon_id}", req);
                         client = this.sdkConfiguration.defaultClient;
@@ -482,16 +482,19 @@ var Coupon = /** @class */ (function () {
      * `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.
      */
-    Coupon.prototype.list = function (req, config) {
+    Coupon.prototype.list = function (cursor, limit, redemptionCode, showArchived, config) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function () {
-            var baseURL, url, client, globalSecurity, properties, headers, queryParams, httpRes, contentType, res, decodedRes;
+            var req, baseURL, url, client, globalSecurity, properties, headers, queryParams, httpRes, contentType, res, decodedRes;
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
-                        if (!(req instanceof utils.SpeakeasyBase)) {
-                            req = new operations.ListCouponsRequest(req);
-                        }
+                        req = new operations.ListCouponsRequest({
+                            cursor: cursor,
+                            limit: limit,
+                            redemptionCode: redemptionCode,
+                            showArchived: showArchived,
+                        });
                         baseURL = utils.templateUrl(this.sdkConfiguration.serverURL, this.sdkConfiguration.serverDefaults);
                         url = baseURL.replace(/\/$/, "") + "/coupons";
                         client = this.sdkConfiguration.defaultClient;
@@ -602,16 +605,18 @@ var Coupon = /** @class */ (function () {
      * [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).
      */
-    Coupon.prototype.listSubscriptions = function (req, config) {
+    Coupon.prototype.listSubscriptions = function (couponId, cursor, limit, config) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function () {
-            var baseURL, url, client, globalSecurity, properties, headers, queryParams, httpRes, contentType, res, decodedRes;
+            var req, baseURL, url, client, globalSecurity, properties, headers, queryParams, httpRes, contentType, res, decodedRes;
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
-                        if (!(req instanceof utils.SpeakeasyBase)) {
-                            req = new operations.ListCouponSubscriptionsRequest(req);
-                        }
+                        req = new operations.ListCouponSubscriptionsRequest({
+                            couponId: couponId,
+                            cursor: cursor,
+                            limit: limit,
+                        });
                         baseURL = utils.templateUrl(this.sdkConfiguration.serverURL, this.sdkConfiguration.serverDefaults);
                         url = utils.generateURL(baseURL, "/coupons/{coupon_id}/subscriptions", req);
                         client = this.sdkConfiguration.defaultClient;

package/dist/sdk/credit.d.ts

@@ -9,26 +9,208 @@ export declare class Credit {
     constructor(sdkConfig: SDKConfiguration);
     /**
      * Create ledger entry by external ID
+     *
+     * @remarks
+     * This endpoint allows you to create a new ledger entry for a specified customer's balance. This can be used to
+     * increment balance, deduct credits, and change the expiry date of existing credits.
+     *
+     * ## Effects of adding a ledger entry
+     * 1. After calling this endpoint, [Fetch Credit Balance](fetch-customer-credits) will return a credit block that
+     *   represents the changes (i.e. balance changes or transfers).
+     * 2. A ledger entry will be added to the credits ledger for this customer, and therefore returned in the
+     *   [View Credits Ledger](fetch-customer-credits) response as well as serialized in the response to this request. In
+     *   the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans
+     *   credit blocks.
+     * 3. If `invoice_settings` is specified, an invoice will be created that reflects the cost of the credits (based on
+     *   `amount` and `per_unit_cost_basis`).
+     *
+     * ## Adding credits
+     *   Adding credits is done by creating an entry of type `increment`. This requires the caller to specify a number of
+     *   credits as well as an optional expiry date in `YYYY-MM-DD` format. Orb also recommends specifying a description
+     *   to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate
+     *   how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.
+     *
+     * The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.
+     *
+     * ```json
+     * {
+     *   "entry_type": "increment",
+     *   "amount": 100,
+     *   "expiry_date": "2022-12-28",
+     *   "per_unit_cost_basis": "0.20",
+     *   "description": "Purchased 100 credits"
+     * }
+     * ```
+     *
+     * Note that by default, Orb will always first increment any _negative_ balance in existing blocks before adding the
+     * remaining amount to the desired credit block.
+     *
+     * ### Invoicing for credits
+     * By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass
+     * `invoice_settings` in the body of this request, Orb will also generate a one-off invoice for the customer for the
+     * credits pre-purchase. Note that you _must_ provide the `per_unit_cost_basis`, since the total charges on the
+     * invoice are calculated by multiplying the cost basis with the number of credit units added.
+     *
+     * ## Deducting Credits
+     * Orb allows you to deduct credits from a customer by creating an entry of type `decrement`. Orb matches the
+     * algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the
+     * deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also
+     * optionally allows specifying a description to assist with auditing.
+     *
+     * The following snippet illustrates a sample request body to decrement credits.
+     *
+     * ```json
+     * {
+     *   "entry_type": "decrement",
+     *   "amount": 20,
+     *   "description": "Removing excess credits"
+     * }
+     * ```
+     *
+     * ## Changing credits expiry
+     * If you'd like to change when existing credits expire, you should create a ledger entry of type `expiration_change`.
+     * For this entry, the required parameter `expiry_date` identifies the _originating_ block, and the required parameter
+     * `target_expiry_date` identifies when the transferred credits should now expire. A new credit block will be created
+     * with expiry date `target_expiry_date`, with the same cost basis data as the original credit block, if present.
+     *
+     * Note that the balance of the block with the given `expiry_date` must be at least equal to the desired transfer
+     * amount determined by the `amount` parameter.
+     *
+     * The following snippet illustrates a sample request body to extend the expiration date of credits by one year:
+     *
+     * ```json
+     * {
+     *   "entry_type": "expiration_change",
+     *   "amount": 10,
+     *   "expiry_date": "2022-12-28",
+     *   "block_id": "UiUhFWeLHPrBY4Ad",
+     *   "target_expiry_date": "2023-12-28",
+     *   "description": "Extending credit validity"
+     * }
+     * ```
+     *
+     * ## Voiding credits
+     *
+     * If you'd like to void a credit block, create a ledger entry of type `void`. For this entry, `block_id` is required
+     * to identify the block, and `amount` indicates how many credits to void, up to the block's initial balance. Pass
+     * in a `void_reason` of `refund` if the void is due to a refund.
+     *
+     * ## Amendment
+     *
+     * If you'd like to undo a decrement on a credit block, create a ledger entry of type `amendment`. For this entry, `block_id`
+     * is required to identify the block that was originally decremented from, and `amount` indicates how many credits to return
+     * to the customer, up to the block's initial balance.
      */
-    addByExternalId(req: operations.CreateLedgerEntryExternalIdRequest, config?: AxiosRequestConfig): Promise<operations.CreateLedgerEntryExternalIdResponse>;
+    addByExternalId(externalCustomerId: string, requestBody?: any, config?: AxiosRequestConfig): Promise<operations.CreateLedgerEntryExternalIdResponse>;
     /**
      * Create ledger entry
+     *
+     * @remarks
+     * This endpoint allows you to create a new ledger entry for a specified customer's balance. This can be used to
+     * increment balance, deduct credits, and change the expiry date of existing credits.
+     *
+     * ## Effects of adding a ledger entry
+     * 1. After calling this endpoint, [Fetch Credit Balance](fetch-customer-credits) will return a credit block that
+     *   represents the changes (i.e. balance changes or transfers).
+     * 2. A ledger entry will be added to the credits ledger for this customer, and therefore returned in the
+     *   [View Credits Ledger](fetch-customer-credits) response as well as serialized in the response to this request. In
+     *   the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans
+     *   credit blocks.
+     * 3. If `invoice_settings` is specified, an invoice will be created that reflects the cost of the credits (based on
+     *   `amount` and `per_unit_cost_basis`).
+     *
+     * ## Adding credits
+     *   Adding credits is done by creating an entry of type `increment`. This requires the caller to specify a number of
+     *   credits as well as an optional expiry date in `YYYY-MM-DD` format. Orb also recommends specifying a description
+     *   to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate
+     *   how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.
+     *
+     * The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.
+     *
+     * ```json
+     * {
+     *   "entry_type": "increment",
+     *   "amount": 100,
+     *   "expiry_date": "2022-12-28",
+     *   "per_unit_cost_basis": "0.20",
+     *   "description": "Purchased 100 credits"
+     * }
+     * ```
+     *
+     * Note that by default, Orb will always first increment any _negative_ balance in existing blocks before adding the
+     * remaining amount to the desired credit block.
+     *
+     * ### Invoicing for credits
+     * By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass
+     * `invoice_settings` in the body of this request, Orb will also generate a one-off invoice for the customer for the
+     * credits pre-purchase. Note that you _must_ provide the `per_unit_cost_basis`, since the total charges on the
+     * invoice are calculated by multiplying the cost basis with the number of credit units added.
+     *
+     * ## Deducting Credits
+     * Orb allows you to deduct credits from a customer by creating an entry of type `decrement`. Orb matches the
+     * algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the
+     * deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also
+     * optionally allows specifying a description to assist with auditing.
+     *
+     * The following snippet illustrates a sample request body to decrement credits.
+     *
+     * ```json
+     * {
+     *   "entry_type": "decrement",
+     *   "amount": 20,
+     *   "description": "Removing excess credits"
+     * }
+     * ```
+     *
+     * ## Changing credits expiry
+     * If you'd like to change when existing credits expire, you should create a ledger entry of type `expiration_change`.
+     * For this entry, the required parameter `expiry_date` identifies the _originating_ block, and the required parameter
+     * `target_expiry_date` identifies when the transferred credits should now expire. A new credit block will be created
+     * with expiry date `target_expiry_date`, with the same cost basis data as the original credit block, if present.
+     *
+     * Note that the balance of the block with the given `expiry_date` must be at least equal to the desired transfer
+     * amount determined by the `amount` parameter.
+     *
+     * The following snippet illustrates a sample request body to extend the expiration date of credits by one year:
+     *
+     * ```json
+     * {
+     *   "entry_type": "expiration_change",
+     *   "amount": 10,
+     *   "expiry_date": "2022-12-28",
+     *   "block_id": "UiUhFWeLHPrBY4Ad",
+     *   "target_expiry_date": "2023-12-28",
+     *   "description": "Extending credit validity"
+     * }
+     * ```
+     *
+     * ## Voiding credits
+     *
+     * If you'd like to void a credit block, create a ledger entry of type `void`. For this entry, `block_id` is required
+     * to identify the block, and `amount` indicates how many credits to void, up to the block's initial balance. Pass
+     * in a `void_reason` of `refund` if the void is due to a refund.
+     *
+     * ## Amendment
+     *
+     * If you'd like to undo a decrement on a credit block, create a ledger entry of type `amendment`. For this entry, `block_id`
+     * is required to identify the block that was originally decremented from, and `amount` indicates how many credits to return
+     * to the customer, up to the block's initial balance.
      */
-    create(req: operations.CreateLedgerEntryRequest, config?: AxiosRequestConfig): Promise<operations.CreateLedgerEntryResponse>;
+    create(customerId: string, requestBody?: any, config?: AxiosRequestConfig): Promise<operations.CreateLedgerEntryResponse>;
     /**
      * Fetch customer credit balance
      *
      * @remarks
      * Returns a paginated list of unexpired, non-zero credit blocks for a customer.
      */
-    fetchBalance(req: operations.FetchCustomerCreditsRequest, config?: AxiosRequestConfig): Promise<operations.FetchCustomerCreditsResponse>;
+    fetchBalance(customerId: string, cursor?: string, limit?: number, config?: AxiosRequestConfig): Promise<operations.FetchCustomerCreditsResponse>;
     /**
      * Fetch customer credit balance by external customer id
      *
      * @remarks
      * Returns a paginated list of unexpired, non-zero credit blocks for a customer.
      */
-    fetchBalanceByExternalId(req: operations.FetchCustomerCreditsExternalIdRequest, config?: AxiosRequestConfig): Promise<operations.FetchCustomerCreditsExternalIdResponse>;
+    fetchBalanceByExternalId(externalCustomerId: string, cursor?: string, limit?: number, config?: AxiosRequestConfig): Promise<operations.FetchCustomerCreditsExternalIdResponse>;
     /**
      * Fetch customer credits ledger
      *