ce-storefront 0.1.0 → 0.2.0

package/FUNCTIONS.md

@@ -0,0 +1,106 @@
+# Standalone Functions
+
+> [!NOTE]
+> This section is useful if you are using a bundler and targetting browsers and
+> runtimes where the size of an application affects performance and load times. 
+
+Every method in this SDK is also available as a standalone function. This
+alternative API is suitable when targetting the browser or serverless runtimes
+and using a bundler to build your application since all unused functionality
+will be tree-shaken away. This includes code for unused methods, Zod schemas,
+encoding helpers and response handlers. The result is dramatically smaller
+impact on the application's final bundle size which grows very slowly as you use
+more and more functionality from this SDK.
+
+Calling methods through the main SDK class remains a valid and generally more
+more ergonomic option. Standalone functions represent an optimisation for a
+specific category of applications.
+
+## Example
+
+```typescript
+import { CeStorefrontCore } from "ce-storefront/core.js";
+import { catalogProductsList } from "ce-storefront/funcs/catalogProductsList.js";
+import { SDKValidationError } from "ce-storefront/models/errors/sdkvalidationerror.js";
+
+// Use `CeStorefrontCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const ceStorefront = new CeStorefrontCore({
+  authorization: "<YOUR_BEARER_TOKEN_HERE>",
+});
+
+async function run() {
+  const res = await catalogProductsList(ceStorefront, {
+    sortBy: "{\"country\":\"asc\",\"city\":\"asc\",\"population\":\"desc\"}",
+  });
+
+  switch (true) {
+    case res.ok:
+      // The success case will be handled outside of the switch block
+      break;
+    case res.error instanceof SDKValidationError:
+      // Pretty-print validation errors.
+      return console.log(res.error.pretty());
+    case res.error instanceof Error:
+      return console.log(res.error);
+    default:
+      // TypeScript's type checking will fail on the following line if the above
+      // cases were not exhaustive.
+      res.error satisfies never;
+      throw new Error("Assertion failed: expected error checks to be exhaustive: " + res.error);
+  }
+
+
+  const { value: result } = res;
+
+  // Handle the result
+  console.log(result);
+}
+
+run();
+```
+
+## Result types
+
+Standalone functions differ from SDK methods in that they return a
+`Result<Value, Error>` type to capture _known errors_ and document them using
+the type system. By avoiding throwing errors, application code maintains clear
+control flow and error-handling become part of the regular flow of application
+code.
+
+> We use the term "known errors" because standalone functions, and JavaScript
+> code in general, can still throw unexpected errors such as `TypeError`s,
+> `RangeError`s and `DOMException`s. Exhaustively catching all errors may be
+> something this SDK addresses in the future. Nevertheless, there is still a lot
+> of benefit from capturing most errors and turning them into values.
+
+The second reason for this style of programming is because these functions will
+typically be used in front-end applications where exception throwing is
+sometimes discouraged or considered unidiomatic. React and similar ecosystems
+and libraries tend to promote this style of programming so that components
+render useful content under all states (loading, success, error and so on).
+
+The general pattern when calling standalone functions looks like this:
+
+```typescript
+import { Core } from "<sdk-package-name>";
+import { fetchSomething } from "<sdk-package-name>/funcs/fetchSomething.js";
+
+const client = new Core();
+
+async function run() {
+  const result = await fetchSomething(client, { id: "123" });
+  if (!result.ok) {
+    // You can throw the error or handle it. It's your choice now.
+    throw result.error;
+  }
+
+  console.log(result.value);
+}
+
+run();
+```
+
+Notably, `result.error` above will have an explicit type compared to a try-catch
+variation where the error in the catch block can only be of type `unknown` (or
+`any` depending on your TypeScript settings).

package/README.md

@@ -10,19 +10,24 @@ Commerce Engine Storefront APIs
 
 <!-- Start Table of Contents [toc] -->
 ## Table of Contents
+<!-- $toc-max-depth=2 -->
+* [ce-storefront](#ce-storefront)
+  * [SDK Installation](#sdk-installation)
+  * [Requirements](#requirements)
+  * [SDK Example Usage](#sdk-example-usage)
+  * [Available Resources and Operations](#available-resources-and-operations)
+  * [Standalone functions](#standalone-functions)
+  * [File uploads](#file-uploads)
+  * [Retries](#retries)
+  * [Error Handling](#error-handling)
+  * [Server Selection](#server-selection)
+  * [Custom HTTP Client](#custom-http-client)
+  * [Authentication](#authentication)
+  * [Debugging](#debugging)
+* [Development](#development)
+  * [Maturity](#maturity)
+  * [Contributions](#contributions)
 
-* [SDK Installation](#sdk-installation)
-* [Requirements](#requirements)
-* [SDK Example Usage](#sdk-example-usage)
-* [Available Resources and Operations](#available-resources-and-operations)
-* [Standalone functions](#standalone-functions)
-* [File uploads](#file-uploads)
-* [Retries](#retries)
-* [Error Handling](#error-handling)
-* [Server Selection](#server-selection)
-* [Custom HTTP Client](#custom-http-client)
-* [Authentication](#authentication)
-* [Debugging](#debugging)
 <!-- End Table of Contents [toc] -->
 
 <!-- Start SDK Installation [installation] -->
@@ -291,90 +296,89 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 
 <summary>Available standalone functions</summary>
 
-- [analyticsTrack](docs/sdks/analytics/README.md#track)
-- [authGenerateOtp](docs/sdks/auth/README.md#generateotp)
-- [authLoginAnonymously](docs/sdks/auth/README.md#loginanonymously)
-- [authLoginWithEmail](docs/sdks/auth/README.md#loginwithemail)
-- [authLoginWithPassword](docs/sdks/auth/README.md#loginwithpassword)
-- [authLoginWithPhone](docs/sdks/auth/README.md#loginwithphone)
-- [authLoginWithWhatsapp](docs/sdks/auth/README.md#loginwithwhatsapp)
-- [authRefreshToken](docs/sdks/auth/README.md#refreshtoken)
-- [authRegisterWithEmail](docs/sdks/auth/README.md#registerwithemail)
-- [authRegisterWithPassword](docs/sdks/auth/README.md#registerwithpassword)
-- [authRegisterWithPhone](docs/sdks/auth/README.md#registerwithphone)
-- [authRegisterWithWhatsapp](docs/sdks/auth/README.md#registerwithwhatsapp)
-- [authUserAddProfileImage](docs/sdks/cestorefrontuser/README.md#addprofileimage)
-- [authUserChangePassword](docs/sdks/cestorefrontuser/README.md#changepassword)
-- [authUserDeactivateAccount](docs/sdks/cestorefrontuser/README.md#deactivateaccount)
-- [authUserDeleteProfileImage](docs/sdks/cestorefrontuser/README.md#deleteprofileimage)
-- [authUserForgotPassword](docs/sdks/cestorefrontuser/README.md#forgotpassword)
-- [authUserGetProfileImage](docs/sdks/cestorefrontuser/README.md#getprofileimage)
-- [authUserGet](docs/sdks/cestorefrontuser/README.md#get)
-- [authUserLogout](docs/sdks/cestorefrontuser/README.md#logout)
-- [authUserResetPassword](docs/sdks/cestorefrontuser/README.md#resetpassword)
-- [authUserUpdateProfileImage](docs/sdks/cestorefrontuser/README.md#updateprofileimage)
-- [authUserUpdate](docs/sdks/cestorefrontuser/README.md#update)
-- [authVerifyEmailPhone](docs/sdks/auth/README.md#verifyemailphone)
-- [authVerifyOtp](docs/sdks/auth/README.md#verifyotp)
-- [campaignsNewsletterSubscribe](docs/sdks/newsletter/README.md#subscribe)
-- [cartsAddItem](docs/sdks/carts/README.md#additem)
-- [cartsCreate](docs/sdks/carts/README.md#create)
-- [cartsDelete](docs/sdks/carts/README.md#delete)
-- [cartsGet](docs/sdks/carts/README.md#get)
-- [catalogCategoriesList](docs/sdks/categories/README.md#list)
-- [catalogProductsGetCrossSells](docs/sdks/products/README.md#getcrosssells)
-- [catalogProductsGetSimilar](docs/sdks/products/README.md#getsimilar)
-- [catalogProductsGetUpsells](docs/sdks/products/README.md#getupsells)
-- [catalogProductsGet](docs/sdks/products/README.md#get)
-- [catalogProductsList](docs/sdks/products/README.md#list)
-- [catalogProductsReviewsCreate](docs/sdks/cestorefrontreviews/README.md#create)
-- [catalogProductsReviewsList](docs/sdks/cestorefrontreviews/README.md#list)
-- [catalogProductsVariantsGet](docs/sdks/variants/README.md#get)
-- [catalogProductsVariantsList](docs/sdks/variants/README.md#list)
-- [catalogSkusList](docs/sdks/skus/README.md#list)
-- [checkoutApplyCoupon](docs/sdks/checkout/README.md#applycoupon)
-- [checkoutRedeemGiftCard](docs/sdks/checkout/README.md#redeemgiftcard)
-- [checkoutRedeemLoyaltyPoints](docs/sdks/checkout/README.md#redeemloyaltypoints)
-- [checkoutRemoveCoupon](docs/sdks/checkout/README.md#removecoupon)
-- [checkoutRemoveCreditBalance](docs/sdks/checkout/README.md#removecreditbalance)
-- [checkoutRemoveLoyaltyPoints](docs/sdks/checkout/README.md#removeloyaltypoints)
-- [checkoutUpdateAddress](docs/sdks/checkout/README.md#updateaddress)
-- [checkoutUseCreditBalance](docs/sdks/checkout/README.md#usecreditbalance)
-- [customersAPIGetCustomersId](docs/sdks/customersapi/README.md#getcustomersid)
-- [customersAPIGetRecommendedProducts](docs/sdks/customersapi/README.md#getrecommendedproducts)
-- [customersAPIPostCustomers](docs/sdks/customersapi/README.md#postcustomers)
-- [customersAPIPutCustomersId](docs/sdks/customersapi/README.md#putcustomersid)
-- [customersAddressesAdd](docs/sdks/addresses/README.md#add)
-- [customersAddressesDelete](docs/sdks/addresses/README.md#delete)
-- [customersAddressesGet](docs/sdks/addresses/README.md#get)
-- [customersAddressesList](docs/sdks/addresses/README.md#list)
-- [customersAddressesUpdate](docs/sdks/addresses/README.md#update)
-- [customersLoyaltyGet](docs/sdks/loyalty/README.md#get)
-- [customersLoyaltyListActivities](docs/sdks/loyalty/README.md#listactivities)
-- [customersReviewsList](docs/sdks/reviews/README.md#list)
-- [offersCouponsList](docs/sdks/coupons/README.md#list)
-- [offersPromotionsList](docs/sdks/promotions/README.md#list)
-- [ordersCancel](docs/sdks/orders/README.md#cancel)
-- [ordersCreate](docs/sdks/orders/README.md#create)
-- [ordersGet](docs/sdks/orders/README.md#get)
-- [ordersList](docs/sdks/orders/README.md#list)
-- [ordersPaymentsList](docs/sdks/cestorefrontpayments/README.md#list)
-- [ordersRefundsList](docs/sdks/refunds/README.md#list)
-- [ordersRetryPayment](docs/sdks/orders/README.md#retrypayment)
-- [ordersShipmentsList](docs/sdks/shipments/README.md#list)
-- [paymentsGenerateHash](docs/sdks/payments/README.md#generatehash)
-- [paymentsGetMethods](docs/sdks/payments/README.md#getmethods)
-- [shippingCheckPincodeServiceability](docs/sdks/shipping/README.md#checkpincodeserviceability)
-- [userNotificationPreferencesCreate](docs/sdks/notificationpreferences/README.md#create)
-- [userNotificationPreferencesGet](docs/sdks/notificationpreferences/README.md#get)
-- [userNotificationPreferencesUpdate](docs/sdks/notificationpreferences/README.md#update)
-- [utilsGetCountries](docs/sdks/utils/README.md#getcountries)
-- [utilsGetPincodes](docs/sdks/utils/README.md#getpincodes)
-- [utilsGetStates](docs/sdks/utils/README.md#getstates)
-- [wishlistAdd](docs/sdks/wishlist/README.md#add)
-- [wishlistDelete](docs/sdks/wishlist/README.md#delete)
-- [wishlistGet](docs/sdks/wishlist/README.md#get)
-
+- [`analyticsTrack`](docs/sdks/analytics/README.md#track) - Track event
+- [`authGenerateOtp`](docs/sdks/auth/README.md#generateotp) - Generate OTP
+- [`authLoginAnonymously`](docs/sdks/auth/README.md#loginanonymously) - Anonymous user
+- [`authLoginWithEmail`](docs/sdks/auth/README.md#loginwithemail) - Login with email
+- [`authLoginWithPassword`](docs/sdks/auth/README.md#loginwithpassword) - Login with password
+- [`authLoginWithPhone`](docs/sdks/auth/README.md#loginwithphone) - Login with phone
+- [`authLoginWithWhatsapp`](docs/sdks/auth/README.md#loginwithwhatsapp) - Login with whatsapp
+- [`authRefreshToken`](docs/sdks/auth/README.md#refreshtoken) - Refresh access token
+- [`authRegisterWithEmail`](docs/sdks/auth/README.md#registerwithemail) - Register with email
+- [`authRegisterWithPassword`](docs/sdks/auth/README.md#registerwithpassword) - Register with password
+- [`authRegisterWithPhone`](docs/sdks/auth/README.md#registerwithphone) - Register with phone
+- [`authRegisterWithWhatsapp`](docs/sdks/auth/README.md#registerwithwhatsapp) - Register with whatsapp
+- [`authUserAddProfileImage`](docs/sdks/cestorefrontuser/README.md#addprofileimage) - Add profile image
+- [`authUserChangePassword`](docs/sdks/cestorefrontuser/README.md#changepassword) - Change password
+- [`authUserDeactivateAccount`](docs/sdks/cestorefrontuser/README.md#deactivateaccount) - Deactivate account
+- [`authUserDeleteProfileImage`](docs/sdks/cestorefrontuser/README.md#deleteprofileimage) - Delete profile image
+- [`authUserForgotPassword`](docs/sdks/cestorefrontuser/README.md#forgotpassword) - Forgot password
+- [`authUserGet`](docs/sdks/cestorefrontuser/README.md#get) - Retrieve a user
+- [`authUserGetProfileImage`](docs/sdks/cestorefrontuser/README.md#getprofileimage) - Retrieve a profile image
+- [`authUserLogout`](docs/sdks/cestorefrontuser/README.md#logout) - Logout user
+- [`authUserResetPassword`](docs/sdks/cestorefrontuser/README.md#resetpassword) - Reset password
+- [`authUserUpdate`](docs/sdks/cestorefrontuser/README.md#update) - Update a user
+- [`authUserUpdateProfileImage`](docs/sdks/cestorefrontuser/README.md#updateprofileimage) - Update profile image
+- [`authVerifyEmailPhone`](docs/sdks/auth/README.md#verifyemailphone) - Check verified email phone
+- [`authVerifyOtp`](docs/sdks/auth/README.md#verifyotp) - Verify OTP
+- [`campaignsNewsletterSubscribe`](docs/sdks/newsletter/README.md#subscribe) - Subscribe to newsletter
+- [`cartsAddItem`](docs/sdks/carts/README.md#additem) - Add/delete cart item
+- [`cartsCreate`](docs/sdks/carts/README.md#create) - Create cart
+- [`cartsDelete`](docs/sdks/carts/README.md#delete) - Delete cart
+- [`cartsGet`](docs/sdks/carts/README.md#get) - Retrieve cart details
+- [`catalogCategoriesList`](docs/sdks/categories/README.md#list) - List all categories
+- [`catalogProductsGet`](docs/sdks/products/README.md#get) - Retrieve a product
+- [`catalogProductsGetCrossSells`](docs/sdks/products/README.md#getcrosssells) - Retrieve cross-sell products
+- [`catalogProductsGetSimilar`](docs/sdks/products/README.md#getsimilar) - Retrieve similar products
+- [`catalogProductsGetUpsells`](docs/sdks/products/README.md#getupsells) - Retrieve up-sell products
+- [`catalogProductsList`](docs/sdks/products/README.md#list) - List all products
+- [`catalogProductsReviewsCreate`](docs/sdks/cestorefrontreviews/README.md#create) - Create product review
+- [`catalogProductsReviewsList`](docs/sdks/cestorefrontreviews/README.md#list) - Retrieve product reviews
+- [`catalogProductsVariantsGet`](docs/sdks/variants/README.md#get) - Retrieve variant detail
+- [`catalogProductsVariantsList`](docs/sdks/variants/README.md#list) - Retrieve product variants
+- [`catalogSkusList`](docs/sdks/skus/README.md#list) - List all SKUs
+- [`checkoutApplyCoupon`](docs/sdks/checkout/README.md#applycoupon) - Apply coupon
+- [`checkoutRedeemGiftCard`](docs/sdks/checkout/README.md#redeemgiftcard) - Redeem gift card
+- [`checkoutRedeemLoyaltyPoints`](docs/sdks/checkout/README.md#redeemloyaltypoints) - Redeem loyalty points
+- [`checkoutRemoveCoupon`](docs/sdks/checkout/README.md#removecoupon) - Remove coupon
+- [`checkoutRemoveCreditBalance`](docs/sdks/checkout/README.md#removecreditbalance) - Remove credit balance
+- [`checkoutRemoveLoyaltyPoints`](docs/sdks/checkout/README.md#removeloyaltypoints) - Remove loyalty points
+- [`checkoutUpdateAddress`](docs/sdks/checkout/README.md#updateaddress) - Update cart address
+- [`checkoutUseCreditBalance`](docs/sdks/checkout/README.md#usecreditbalance) - Use credit balance
+- [`customersAddressesAdd`](docs/sdks/addresses/README.md#add) - Add address
+- [`customersAddressesDelete`](docs/sdks/addresses/README.md#delete) - Remove particular address
+- [`customersAddressesGet`](docs/sdks/addresses/README.md#get) - Retrieve particular address
+- [`customersAddressesList`](docs/sdks/addresses/README.md#list) - Retrieve all addresses
+- [`customersAddressesUpdate`](docs/sdks/addresses/README.md#update) - Update particular address
+- [`customersAPIGetCustomersId`](docs/sdks/customersapi/README.md#getcustomersid) - Retrieve customer detail
+- [`customersAPIGetRecommendedProducts`](docs/sdks/customersapi/README.md#getrecommendedproducts) - List all recommended products
+- [`customersAPIPostCustomers`](docs/sdks/customersapi/README.md#postcustomers) - Create customer
+- [`customersAPIPutCustomersId`](docs/sdks/customersapi/README.md#putcustomersid) - Update customer detail
+- [`customersLoyaltyGet`](docs/sdks/loyalty/README.md#get) - Retrieve loyalty details
+- [`customersLoyaltyListActivities`](docs/sdks/loyalty/README.md#listactivities) - List all loyalty points activity
+- [`customersReviewsList`](docs/sdks/reviews/README.md#list) - Retrieve all reviews
+- [`offersCouponsList`](docs/sdks/coupons/README.md#list) - Retrieve all coupons
+- [`offersPromotionsList`](docs/sdks/promotions/README.md#list) - Retrieve all promotions
+- [`ordersCancel`](docs/sdks/orders/README.md#cancel) - Cancel order
+- [`ordersCreate`](docs/sdks/orders/README.md#create) - Create order
+- [`ordersGet`](docs/sdks/orders/README.md#get) - Retrieve order detail
+- [`ordersList`](docs/sdks/orders/README.md#list) - Retrieve all orders
+- [`ordersPaymentsList`](docs/sdks/cestorefrontpayments/README.md#list) - Retrieve order payments
+- [`ordersRefundsList`](docs/sdks/refunds/README.md#list) - Retrieve order refunds
+- [`ordersRetryPayment`](docs/sdks/orders/README.md#retrypayment) - Retry payment
+- [`ordersShipmentsList`](docs/sdks/shipments/README.md#list) - Retrieve order shipments
+- [`paymentsGenerateHash`](docs/sdks/payments/README.md#generatehash) - Generate hash
+- [`paymentsGetMethods`](docs/sdks/payments/README.md#getmethods) - Retrieve available payment methods
+- [`shippingCheckPincodeServiceability`](docs/sdks/shipping/README.md#checkpincodeserviceability) - Check pincode serviceability
+- [`userNotificationPreferencesCreate`](docs/sdks/notificationpreferences/README.md#create) - Create user notification preferences
+- [`userNotificationPreferencesGet`](docs/sdks/notificationpreferences/README.md#get) - Retrieve user notification preferences
+- [`userNotificationPreferencesUpdate`](docs/sdks/notificationpreferences/README.md#update) - Update user notification preferences
+- [`utilsGetCountries`](docs/sdks/utils/README.md#getcountries) - Retrieve all countries
+- [`utilsGetPincodes`](docs/sdks/utils/README.md#getpincodes) - Retrieve pincodes
+- [`utilsGetStates`](docs/sdks/utils/README.md#getstates) - Retrieve country wise states
+- [`wishlistAdd`](docs/sdks/wishlist/README.md#add) - Add product to wishlist
+- [`wishlistDelete`](docs/sdks/wishlist/README.md#delete) - Delete product from wishlist
+- [`wishlistGet`](docs/sdks/wishlist/README.md#get) - Retrieve wishlist
 
 </details>
 <!-- End Standalone functions [standalone-funcs] -->
@@ -395,6 +399,7 @@ Certain SDK methods accept files as part of a multi-part request. It is possible
 
 ```typescript
 import { CeStorefront } from "ce-storefront";
+import { openAsBlob } from "node:fs";
 
 const ceStorefront = new CeStorefront({
   authorization: "<YOUR_BEARER_TOKEN_HERE>",
@@ -403,6 +408,9 @@ const ceStorefront = new CeStorefront({
 async function run() {
   const result = await ceStorefront.auth.user.addProfileImage({
     id: "<id>",
+    requestBody: {
+      image: await openAsBlob("example.file"),
+    },
   });
 
   // Handle the result
@@ -486,16 +494,25 @@ run();
 <!-- Start Error Handling [errors] -->
 ## Error Handling
 
-All SDK methods return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.
+All SDK methods return a response object or throw an error. By default, an API error will throw a `errors.SDKError`.
+
+If a HTTP request fails, an operation my also throw an error from the `models/errors/httpclienterrors.ts` module:
 
-| Error Object        | Status Code         | Content Type        |
-| ------------------- | ------------------- | ------------------- |
-| errors.Unauthorized | 401                 | application/json    |
-| errors.NotFound     | 404                 | application/json    |
-| errors.SDKError     | 4xx-5xx             | */*                 |
+| HTTP Client Error                                    | Description                                          |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| RequestAbortedError                                  | HTTP request was aborted by the client               |
+| RequestTimeoutError                                  | HTTP request timed out due to an AbortSignal signal  |
+| ConnectionError                                      | HTTP client was unable to make a request to a server |
+| InvalidRequestError                                  | Any input used to create a request is invalid        |
+| UnexpectedClientError                                | Unrecognised or unexpected error                     |
 
-Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The `SDKValidationError` that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging. 
+In addition, when custom error responses are specified for an operation, the SDK may throw their associated Error type. You can refer to respective *Errors* tables in SDK docs for more details on possible error types for each operation. For example, the `list` method may throw the following errors:
 
+| Error Type          | Status Code | Content Type     |
+| ------------------- | ----------- | ---------------- |
+| errors.Unauthorized | 401         | application/json |
+| errors.NotFound     | 404         | application/json |
+| errors.SDKError     | 4XX, 5XX    | \*/\*            |
 
 ```typescript
 import { CeStorefront } from "ce-storefront";
@@ -547,6 +564,8 @@ async function run() {
 run();
 
 ```
+
+Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The `SDKValidationError` that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.
 <!-- End Error Handling [errors] -->
 
 <!-- Start Server Selection [server] -->
@@ -554,12 +573,16 @@ run();
 
 ### Select Server by Index
 
-You can override the default server globally by passing a server index to the `serverIdx` optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:
+You can override the default server globally by passing a server index to the `serverIdx: number` optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:
+
+| #   | Server                                                              | Variables         | Default values |
+| --- | ------------------------------------------------------------------- | ----------------- | -------------- |
+| 0   | `https://staging.api.commercengine.io/api/v1/{store_id}/storefront` | `storeId: string` | `"x2yh61zw4k"` |
+| 1   | `https://prod.api.commercengine.io/api/v1/{store_id}/storefront`    | `storeId: string` | `"x2yh61zw4k"` |
 
-| # | Server | Variables |
-| - | ------ | --------- |
-| 0 | `https://staging.api.commercengine.io/api/v1/{store_id}/storefront` | `store_id` (default is `x2yh61zw4k`) |
-| 1 | `https://prod.api.commercengine.io/api/v1/{store_id}/storefront` | `store_id` (default is `x2yh61zw4k`) |
+If the selected server has variables, you may override their default values through the additional parameters made available in the SDK constructor.
+
+#### Example
 
 ```typescript
 import { CeStorefront } from "ce-storefront";
@@ -582,21 +605,15 @@ run();
 
 ```
 
-#### Variables
-
-Some of the server options above contain variables. If you want to set the values of those variables, the following optional parameters are available when initializing the SDK client instance:
- * `storeId: string`
-
 ### Override Server URL Per-Client
 
-The default server can also be overridden globally by passing a URL to the `serverURL` optional parameter when initializing the SDK client instance. For example:
-
+The default server can also be overridden globally by passing a URL to the `serverURL: string` optional parameter when initializing the SDK client instance. For example:
 ```typescript
 import { CeStorefront } from "ce-storefront";
 
 const ceStorefront = new CeStorefront({
   serverURL:
-    "https://staging.api.commercengine.io/api/v1/{store_id}/storefront",
+    "https://staging.api.commercengine.io/api/v1/x2yh61zw4k/storefront",
   authorization: "<YOUR_BEARER_TOKEN_HERE>",
 });
 
@@ -670,9 +687,9 @@ const sdk = new CeStorefront({ httpClient });
 
 This SDK supports the following security scheme globally:
 
-| Name            | Type            | Scheme          |
-| --------------- | --------------- | --------------- |
-| `authorization` | http            | HTTP Bearer     |
+| Name            | Type | Scheme      |
+| --------------- | ---- | ----------- |
+| `authorization` | http | HTTP Bearer |
 
 To authenticate with the API the `authorization` parameter must be set when initializing the SDK client instance. For example:
 ```typescript

package/RUNTIMES.md

@@ -0,0 +1,22 @@
+# Supported JavaScript runtimes
+
+This SDK is intended to be used in JavaScript runtimes that support the following features:
+
+* [Web Fetch API][web-fetch]
+* [Web Streams API][web-streams] and in particular `ReadableStream`
+* [Async iterables][async-iter] using `Symbol.asyncIterator`
+
+[web-fetch]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+[web-streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+[async-iter]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+
+Runtime environments that are explicitly supported are:
+
+- Evergreen browsers which include: Chrome, Safari, Edge, Firefox
+- Node.js active and maintenance LTS releases
+  - Currently, this is v18 and v20
+- Bun v1 and above
+- Deno v1.39
+  - Note that Deno does not currently have native support for streaming file uploads backed by the filesystem ([issue link][deno-file-streaming])
+
+[deno-file-streaming]: https://github.com/denoland/deno/issues/11018