chore(types,js-sdk,medusa): Add TSDocs for store and auth's JS SDK + small type fixes (#9657)

* added jsdocs

* more tsdocs

* added for cart completion

* finish up the store tsdocs

packages/core/js-sdk/src/auth/index.ts

@@ -11,6 +11,28 @@ export class Auth {
     this.config = config
   }
 
+  /**
+   * This method is used to retrieve a registration JWT token for a user, customer, or custom actor type. It sends a request to the
+   * [Retrieve Registration Token API route](https://docs.medusajs.com/v2/api/store#auth_postactor_typeauth_provider_register).
+   * 
+   * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
+   * @param method - The authentication provider to use. For example, `emailpass` or `google`.
+   * @param payload - The data to pass in the request's body for authentication. When using the `emailpass` provider,
+   * you pass the email and password.
+   * @returns The JWT token used for registration later.
+   * 
+   * @example
+   * sdk.auth.register(
+   *   "customer",
+   *   "emailpass",
+   *   {
+   *     email: "customer@gmail.com",
+   *     password: "supersecret"
+   *   }
+   * ).then((token) => {
+   *   console.log(token)
+   * })
+   */
   register = async (
     actor: string,
     method: string,
@@ -29,6 +51,34 @@ export class Auth {
     return token
   }
 
+  /**
+   * This method retrieves the JWT authenticated token for an admin user, customer, or custom
+   * actor type. It sends a request to the [Authenticate API Route](https://docs.medusajs.com/v2/api/admin#auth_postactor_typeauth_provider).
+   * 
+   * If the `auth.type` of the SDK is set to `session`, this method will also send a request to the
+   * [Set Authentication Session API route](https://docs.medusajs.com/v2/api/admin#auth_postsession).
+   * 
+   * Subsequent requests using the SDK will automatically have the necessary authentication headers / session
+   * set.
+   * 
+   * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
+   * @param method - The authentication provider to use. For example, `emailpass` or `google`.
+   * @param payload - The data to pass in the request's body for authentication. When using the `emailpass` provider,
+   * you pass the email and password.
+   * @returns The authentication JWT token
+   * 
+   * @example
+   * sdk.auth.login(
+   *   "customer",
+   *   "emailpass",
+   *   {
+   *     email: "customer@gmail.com",
+   *     password: "supersecret"
+   *   }
+   * ).then((token) => {
+   *   console.log(token)
+   * })
+   */
   login = async (
     actor: string,
     method: string,
@@ -53,7 +103,31 @@ export class Auth {
     return token as string
   }
 
-  // The callback expects all query parameters from the Oauth callback to be passed to the backend, and the provider is in charge of parsing and validating them
+  /**
+   * This method is used to validate an Oauth callback from a third-party service, such as Google, for an admin user, customer, or custom actor types.
+   * It sends a request to the [Validate Authentication Callback](https://docs.medusajs.com/v2/api/admin#auth_postactor_typeauth_providercallback).
+   * 
+   * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
+   * @param method - The authentication provider to use. For example, `google`.
+   * @param query - The query parameters from the Oauth callback, which should be passed to the API route.
+   * @returns The authentication JWT token
+   * 
+   * @example
+   * sdk.auth.callback(
+   *   "customer",
+   *   "google",
+   *   {
+   *     code: "123",
+   *   }
+   * ).then((token) => {
+   *   console.log(token)
+   * })
+   * 
+   * 
+   * @privateRemarks
+   * The callback expects all query parameters from the Oauth callback to be passed to 
+   * the backend, and the provider is in charge of parsing and validating them
+   */
   callback = async (
     actor: string,
     method: string,
@@ -71,6 +145,18 @@ export class Auth {
     return token
   }
 
+  /**
+   * This method refreshes a JWT authentication token, which is useful after validating the Oauth callback
+   * with {@link callback}. It sends a request to the [Refresh Authentication Token API route](https://docs.medusajs.com/v2/api/admin#auth_postadminauthtokenrefresh).
+   * 
+   * @returns The refreshed JWT authentication token.
+   * 
+   * @example
+   * sdk.auth.refresh()
+   * .then((token) => {
+   *   console.log(token)
+   * })
+   */
   refresh = async () => {
     const { token } = await this.client.fetch<{ token: string }>(
       "/auth/token/refresh",
@@ -85,6 +171,16 @@ export class Auth {
     return token
   }
 
+  /**
+   * This method deletes the authentication session of the currently logged-in user to log them out.
+   * It sends a request to the [Delete Authentication Session API route](https://docs.medusajs.com/v2/api/admin#auth_deletesession).
+   * 
+   * @example
+   * sdk.auth.logout()
+   * .then(() => {
+   *   // user is logged out
+   * })
+   */
   logout = async () => {
     if (this.config?.auth?.type === "session") {
       await this.client.fetch("/auth/session", {
@@ -95,10 +191,40 @@ export class Auth {
     this.client.clearToken()
   }
 
+  /**
+   * This method requests a reset password token for an admin user, customer, or custom actor type.
+   * It sends a request to the [Generate Reset Password Token API route](https://docs.medusajs.com/v2/api/admin#auth_postactor_typeauth_providerresetpassword).
+   * 
+   * To reset the password later using the token delivered to the user, use the {@link updateProvider} method.
+   * 
+   * Related guide: [How to allow customers to reset their passwords in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password).
+   * 
+   * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
+   * @param provider - The authentication provider to use. For example, `emailpass`.
+   * @param body - The data required to identify the user.
+   * 
+   * @example
+   * sdk.auth.resetPassword(
+   *   "customer",
+   *   "emailpass",
+   *   {
+   *     identifier: "customer@gmail.com"
+   *   }
+   * )
+   * .then(() => {
+   *   // user receives token
+   * })
+   */
   resetPassword = async (
     actor: string,
     provider: string,
-    body: { identifier: string }
+    body: {
+      /**
+       * The user's identifier. For example, when using the `emailpass` provider,
+       * this would be the user's email.
+       */ 
+      identifier: string
+    }
   ) => {
     await this.client.fetch(`/auth/${actor}/${provider}/reset-password`, {
       method: "POST",
@@ -107,6 +233,34 @@ export class Auth {
     })
   }
 
+  /**
+   * This method is used to update user-related data authentication data.
+   * 
+   * More specifically, use this method when updating the password of an admin user, customer, or 
+   * custom actor type after requesting to reset their password with {@link resetPassword}.
+   * 
+   * This method sends a request to [this API route](https://docs.medusajs.com/v2/api/admin#auth_postactor_typeauth_providerupdate).
+   * 
+   * Related guide: [How to allow customers to reset their passwords in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password).
+   * 
+   * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
+   * @param provider - The authentication provider to use. For example, `emailpass`.
+   * @param body - The data necessary to update the user's authentication data. When resetting the user's password, 
+   * send the `email` and `password` properties.
+   * 
+   * @example
+   * sdk.auth.updateProvider(
+   *   "customer",
+   *   "emailpass",
+   *   {
+   *     email: "customer@gmail.com",
+   *     password: "supersecret"
+   *   }
+   * )
+   * .then(() => {
+   *   // password updated
+   * })
+   */
   updateProvider = async (
     actor: string,
     provider: string,
@@ -118,6 +272,9 @@ export class Auth {
     })
   }
 
+  /**
+   * @ignore
+   */
   private setToken_ = async (token: string) => {
     // By default we just set the token in the configured storage, if configured to use sessions we convert it into session storage instead.
     if (this.config?.auth?.type === "session") {

packages/core/js-sdk/src/types.ts

@@ -22,8 +22,14 @@ export type Config = {
 export type FetchParams = Parameters<typeof fetch>
 
 export type ClientHeaders =
-  // The `tags` header is specifically added for nextJS, as they follow a non-standard header format
+  Record<string, string | null | { 
-  Record<string, string | null | { tags: string[] }>
+    /**
+     * Tags to cache data under for Next.js applications.
+     * 
+     * Learn more in [Next.js's documentation](https://nextjs.org/docs/app/building-your-application/caching#fetch-optionsnexttags-and-revalidatetag).
+     */
+    tags: string[]
+  }>
 
 export type FetchInput = FetchParams[0]
 

packages/core/types/src/http/cart/store/entities.ts

@@ -13,30 +13,69 @@ import {
 } from "../common"
 
 export interface StoreCart extends Omit<BaseCart, "items"> {
+  /**
+   * The cart's shipping address.
+   */
   shipping_address?: StoreCartAddress
+  /**
+   * The cart's billing address.
+   */
   billing_address?: StoreCartAddress
+  /**
+   * The cart's items.
+   */
   items?: StoreCartLineItem[]
+  /**
+   * The cart's shipping methods.
+   */
   shipping_methods?: StoreCartShippingMethod[]
+  /**
+   * The cart's payment collection.
+   */
   payment_collection?: StorePaymentCollection
+  /**
+   * The cart's region
+   */
   region?: StoreRegion
 }
 export interface StoreCartLineItem
   extends Omit<BaseCartLineItem, "product" | "variant" | "cart"> {
+  /**
+   * The product this item is created for.
+   */
   product?: StoreProduct
+  /**
+   * The variant added to the cart.
+   */
   variant?: StoreProductVariant
+  /**
+   * The cart this item belongs to.
+   */
   cart: StoreCart
+  /**
+   * The item's tax lines.
+   */
   tax_lines?: (BaseLineItemTaxLine & {
     item: StoreCartLineItem
   })[]
+  /**
+   * The item's adjustments.
+   */
   adjustments?: (BaseLineItemAdjustment & {
     item: StoreCartLineItem
   })[]
 }
 export interface StoreCartAddress extends BaseCartAddress {}
 export interface StoreCartShippingMethod extends BaseCartShippingMethod {
+  /**
+   * The shipping method's tax lines.
+   */
   tax_lines?: (BaseShippingMethodTaxLine & {
     shipping_method: StoreCartShippingMethod
   })[]
+  /**
+   * The shipping method's adjustments.
+   */
   adjustments?: (BaseShippingMethodAdjustment & {
     shipping_method: StoreCartShippingMethod
   })[]

packages/core/types/src/http/cart/store/payloads.ts

@@ -1,38 +1,112 @@
 export interface StoreCreateCart {
+  /**
+   * The ID of the region that the cart is created in.
+   */
   region_id?: string
+  /**
+   * The cart's shipping address.
+   */
   shipping_address?: StoreAddAddress
+  /**
+   * The cart's billing address.
+   */
   billing_address?: StoreAddAddress
+  /**
+   * The email of the customer associated with the cart.
+   */
   email?: string
+  /**
+   * The cart's currency code. If not provided, the region's currency
+   * code is used.
+   */
   currency_code?: string
+  /**
+   * The cart's items.
+   */
   items?: StoreAddCartLineItem[]
+  /**
+   * The ID of the associated sales channel. Only products in the same sales channel
+   * can be added to the cart.
+   */
   sales_channel_id?: string
+  /**
+   * The promotion codes to apply on the cart.
+   */
   promo_codes?: string[]
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface StoreUpdateCart {
+  /**
+   * The ID of the region that the cart is in.
+   */
   region_id?: string
+  /**
+   * The cart's shipping address.
+   */
   shipping_address?: StoreAddAddress | string
+  /**
+   * The cart's billing address.
+   */
   billing_address?: StoreAddAddress | string
+  /**
+   * The email of the customer associated with the cart.
+   */
   email?: string
+  /**
+   * The ID of the associated sales channel. Only products in the same sales channel
+   * can be added to the cart.
+   */
   sales_channel_id?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
+  /**
+   * The promotion codes to apply on the cart.
+   */
   promo_codes?: string[]
 }
 
 export interface StoreAddCartLineItem {
+  /**
+   * The ID of the product variant to add to the cart.
+   */
   variant_id: string
+  /**
+   * The item's quantity in the cart.
+   */
   quantity: number
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface StoreUpdateCartLineItem {
+  /**
+   * The item's quantity.
+   */
   quantity: number
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface StoreAddCartShippingMethods {
+  /**
+   * The id of the chosen shipping option.
+   */
   option_id: string
+  /**
+   * Data useful for the associated fulfillment provider.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
   data?: Record<string, unknown>
 }
 

packages/core/types/src/http/cart/store/responses.ts

@@ -3,21 +3,49 @@ import { StoreOrder } from "../../order"
 import { StoreCart } from "./entities"
 
 export interface StoreCartResponse {
+  /**
+   * The cart's details.
+   */
   cart: StoreCart
 }
 
 export type StoreCompleteCartResponse =
   | {
+    /**
+     * The response's type. If `cart`, then an error has occurred.
+     */
       type: "cart"
+      /**
+       * The cart's details.
+       */
       cart: StoreCart
+      /**
+       * The error that occurred while completing the cart.
+       */
       error: {
+        /**
+         * The error message.
+         */
         message: string
+        /**
+         * The error name.
+         */
         name: string
+        /**
+         * The error type.
+         */
         type: string
       }
     }
   | {
+    /**
+     * The response's type. If `order`, then the cart
+     * was completed and an order was placed.
+     */
       type: "order"
+      /**
+       * The order's details.
+       */
       order: StoreOrder
     }
 

packages/core/types/src/http/collection/common.ts

@@ -1,15 +1,39 @@
 import { BaseFilterable, OperatorMap } from "../../dal"
 import { FindParams, SelectParams } from "../common"
-import { AdminProduct } from "../product"
+import { BaseProduct } from "../product/common"
 
 export interface BaseCollection {
+  /**
+   * The collection's ID.
+   */
   id: string
+  /**
+   * The collection's title.
+   */
   title: string
+  /**
+   * The collection's handle.
+   */
   handle: string
+  /**
+   * The date the collection was created.
+   */
   created_at: string
+  /**
+   * The date the collection was updated.
+   */
   updated_at: string
+  /**
+   * The date the collection was deleted.
+   */
   deleted_at: string | null
-  products?: AdminProduct[]
+  /**
+   * The collection's products.
+   */
+  products?: BaseProduct[]
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
 }
 
@@ -18,10 +42,28 @@ export interface BaseCollectionParams extends SelectParams {}
 export interface BaseCollectionListParams
   extends FindParams,
     BaseFilterable<BaseCollectionListParams> {
+  /**
+   * A query or keywords to search the collection's searchable fields by.
+   */
   q?: string
+  /**
+   * Filter by collection ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by collection handle(s).
+   */
   handle?: string | string[]
+  /**
+   * Filter by collection title(s).
+   */
   title?: string | string[]
+  /**
+   * Apply filters on collection creation dates.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on collection update dates.
+   */
   updated_at?: OperatorMap<string>
 }

packages/core/types/src/http/collection/store/entities.ts

@@ -2,5 +2,8 @@ import { StoreProduct } from "../../product"
 import { BaseCollection } from "../common"
 
 export interface StoreCollection extends Omit<BaseCollection, "products"> {
+  /**
+   * The collection's products.
+   */
   products?: StoreProduct[]
 }

packages/core/types/src/http/collection/store/queries.ts

@@ -1,7 +1,5 @@
-import { OperatorMap } from "../../../dal"
 import { BaseCollectionListParams } from "../common"
 
 export interface StoreCollectionFilters
   extends Omit<BaseCollectionListParams, "id"> {
-  deleted_at?: OperatorMap<string>
 }

packages/core/types/src/http/collection/store/responses.ts

@@ -2,9 +2,15 @@ import { StoreCollection } from "."
 import { PaginatedResponse } from "../../common"
 
 export interface StoreCollectionResponse {
+  /**
+   * The collection's details.
+   */
   collection: StoreCollection
 }
 
 export type StoreCollectionListResponse = PaginatedResponse<{
+  /**
+   * The paginated list of collections.
+   */
   collections: StoreCollection[]
 }>

packages/core/types/src/http/common/request.ts

@@ -1,10 +1,27 @@
 export interface SelectParams {
+  /**
+   * The fields and relations to retrieve.
+   * 
+   * Learn more in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations).
+   */
   fields?: string
 }
 
 export interface FindParams extends SelectParams {
+  /**
+   * The maximum number of items to retrieve.
+   */
   limit?: number
+  /**
+   * The number of items to skip before retrieving the returned items.
+   */
   offset?: number
+  /**
+   * The field to sort by and in which order.
+   * 
+   * @example
+   * -created_at
+   */
   order?: string
 }
 

packages/core/types/src/http/common/response.ts

@@ -26,8 +26,17 @@ export type DeleteResponseWithParent<
 }
 
 export type PaginatedResponse<T> = {
+  /**
+   * The maximum number of items retrieved.
+   */
   limit: number
+  /**
+   * The number of items to skip before retrieving the returned items.
+   */
   offset: number
+  /**
+   * The total number of items.
+   */
   count: number
 } & T
 

packages/core/types/src/http/customer/common.ts

@@ -11,40 +11,139 @@ export interface BaseCustomerGroup {
 }
 
 export interface BaseCustomerAddress {
+  /**
+   * The address's ID.
+   */
   id: string
+  /**
+   * The address's name.
+   */
   address_name: string | null
+  /**
+   * Whether the address is used by default for shipping.
+   */
   is_default_shipping: boolean
+  /**
+   * Whether the address is used by default for billing.
+   */
   is_default_billing: boolean
+  /**
+   * The ID of the customer that the address belongs to.
+   */
   customer_id: string
+  /**
+   * The address's company.
+   */
   company: string | null
+  /**
+   * The address's first name.
+   */
   first_name: string | null
+  /**
+   * The address's last name.
+   */
   last_name: string | null
+  /**
+   * The address's first line.
+   */
   address_1: string | null
+  /**
+   * The address's second line.
+   */
   address_2: string | null
+  /**
+   * The address's city.
+   */
   city: string | null
+  /**
+   * The address's country code.
+   * 
+   * @example
+   * us
+   */
   country_code: string | null
+  /**
+   * The address's province.
+   */
   province: string | null
+  /**
+   * The address's postal code.
+   */
   postal_code: string | null
+  /**
+   * The address's phone.
+   */
   phone: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The date the address was created.
+   */
   created_at: string
+  /**
+   * The date the address was updated.
+   */
   updated_at: string
 }
 
 export interface BaseCustomer {
+  /**
+   * The customer's ID.
+   */
   id: string
+  /**
+   * The customer's email.
+   */
   email: string
+  /**
+   * The ID of the customer's default billing address.
+   */
   default_billing_address_id: string | null
+  /**
+   * The ID of the customer's default shipping address.
+   */
   default_shipping_address_id: string | null
+  /**
+   * The customer's company name.
+   */
   company_name: string | null
+  /**
+   * The customer's first name.
+   */
   first_name: string | null
+  /**
+   * The customer's last name.
+   */
   last_name: string | null
+  /**
+   * The customer's addresses
+   */
   addresses: BaseCustomerAddress[]
+  /**
+   * The customer's phone.
+   */
   phone?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
+  /**
+   * The ID of the user that created the customer.
+   */
   created_by?: string | null
+  /**
+   * The date the customer was deleted.
+   */
   deleted_at?: Date | string | null
+  /**
+   * The date the customer was created.
+   */
   created_at?: Date | string
+  /**
+   * The date the customer was updated.
+   */
   updated_at?: Date | string
 }
 
@@ -73,61 +172,202 @@ export interface BaseCustomerFilters
 
 export interface BaseCustomerAddressFilters
   extends BaseFilterable<BaseCustomerAddressFilters> {
+  /**
+   * A query or keyword to search the address's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by company name(s).
+   */
   company?: string[] | string
+  /**
+   * Filter by cities.
+   */
   city?: string[] | string
+  /**
+   * Filter by country code(s).
+   */
   country_code?: string[] | string
+  /**
+   * Filter by province(s).
+   */
   province?: string[] | string
+  /**
+   * Filter by postal code(s).
+   */
   postal_code?: string[] | string
 }
 
 export interface BaseCreateCustomer {
+  /**
+   * The customer's email.
+   */
   email: string
+  /**
+   * The customer's company name.
+   */
   company_name?: string
+  /**
+   * The customer's first name.
+   */
   first_name?: string
+  /**
+   * The customer's last name.
+   */
   last_name?: string
+  /**
+   * The customer's phone.
+   */
   phone?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface BaseUpdateCustomer {
+  /**
+   * The customer's company name.
+   */
   company_name?: string
+  /**
+   * The customer's first name.
+   */
   first_name?: string
+  /**
+   * The customer's last name.
+   */
   last_name?: string
+  /**
+   * The customer's phone.
+   */
   phone?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface BaseCreateCustomerAddress {
+  /**
+   * The address's first name.
+   */
   first_name?: string
+  /**
+   * The address's last name.
+   */
   last_name?: string
+  /**
+   * The address's phone.
+   */
   phone?: string
+  /**
+   * The address's company.
+   */
   company?: string
+  /**
+   * The address's first line.
+   */
   address_1?: string
+  /**
+   * The address's second line.
+   */
   address_2?: string
+  /**
+   * The address's city.
+   */
   city?: string
+  /**
+   * The address's country code.
+   * 
+   * @example
+   * us
+   */
   country_code?: string
+  /**
+   * The address's province.
+   */
   province?: string
+  /**
+   * The address's postal code.
+   */
   postal_code?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
+  /**
+   * The address's name.
+   */
   address_name?: string
+  /**
+   * Whether the address is used by default for shipping.
+   */
   is_default_shipping?: boolean
+  /**
+   * Whether the address is used by default for billing.
+   */
   is_default_billing?: boolean
 }
 
 export interface BaseUpdateCustomerAddress {
+  /**
+   * The address's first name.
+   */
   first_name?: string
+  /**
+   * The address's last name.
+   */
   last_name?: string
+  /**
+   * The address's phone.
+   */
   phone?: string
+  /**
+   * The address's company.
+   */
   company?: string
+  /**
+   * The address's first line.
+   */
   address_1?: string
+  /**
+   * The address's second line.
+   */
   address_2?: string
+  /**
+   * The address's city.
+   */
   city?: string
+  /**
+   * The address's country code.
+   * 
+   * @example
+   * us
+   */
   country_code?: string
+  /**
+   * The address's province.
+   */
   province?: string
+  /**
+   * The address's postal code.
+   */
   postal_code?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
+  /**
+   * The address's name.
+   */
   address_name?: string
+  /**
+   * Whether the address is used by default for shipping.
+   */
   is_default_shipping?: boolean
+  /**
+   * Whether the address is used by default for billing.
+   */
   is_default_billing?: boolean
 }

packages/core/types/src/http/customer/store/entities.ts

@@ -1,6 +1,9 @@
 import { BaseCustomer, BaseCustomerAddress } from "../common"
 
 export interface StoreCustomer extends Omit<BaseCustomer, "created_by"> {
+  /**
+   * The customer's address.
+   */
   addresses: StoreCustomerAddress[]
 }
 export interface StoreCustomerAddress extends BaseCustomerAddress {}

packages/core/types/src/http/customer/store/responses.ts

@@ -2,15 +2,26 @@ import { DeleteResponseWithParent, PaginatedResponse } from "../../common"
 import { StoreCustomer, StoreCustomerAddress } from "./entities"
 
 export interface StoreCustomerResponse {
+  /**
+   * The customer's details.
+   */
   customer: StoreCustomer
 }
 
 export interface StoreCustomerAddressResponse {
+  /**
+   * The address's details.
+   */
   address: StoreCustomerAddress
 }
 
 export interface StoreCustomerAddressListResponse
-  extends PaginatedResponse<{ addresses: StoreCustomerAddress[] }> {}
+  extends PaginatedResponse<{ 
+    /**
+     * The paginated list of addresses.
+     */
+    addresses: StoreCustomerAddress[] 
+  }> {}
 
 export type StoreCustomerAddressDeleteResponse = DeleteResponseWithParent<
   "address",

packages/core/types/src/http/fulfillment/store/index.ts

@@ -1,22 +1,76 @@
+import { ShippingOptionPriceType } from "../../../fulfillment"
+
 // TODO: The way the cart shipping options are listed now differs from most other endpoints as it is fetched in a workflow.
 // We should consider refactoring this to be more consistent with other endpoints.
 export interface StoreCartShippingOption {
+  /**
+   * The shipping option's ID.
+   */
   id: string
+  /**
+   * The shipping option's name.
+   */
   name: string
-  price_type: string
+  /**
+   * The type of the shipping option's price. `flat` means the price
+   * is fixed, whereas `calculated` means the price is calculated by the 
+   * associated fulfillment provider.
+   */
+  price_type: ShippingOptionPriceType
+  /**
+   * The ID of the associated service zone.
+   */
   service_zone_id: string
+  /**
+   * The ID of the associated shipping profile.
+   */
   shipping_profile_id: string
+  /**
+   * The ID of the fulfillment provider used to handle shipping.
+   */
   provider_id: string
+  /**
+   * The data useful for the fulfillment provider when handling the shipment and fulfillment.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
   data: Record<string, unknown> | null
+  /**
+   * The shipping option's type.
+   */
   type: {
+    /**
+     * The type's ID.
+     */
     id: string
+    /**
+     * The type's label.
+     */
     label: string
+    /**
+     * The type's description.
+     */
     description: string
+    /**
+     * The type's code.
+     */
     code: string
   }
+  /**
+   * The details of the associated fulfillment provider.
+   */
   provider: {
+    /**
+     * The fulfillment provider's ID.
+     */
     id: string
+    /**
+     * Whether the fulfillment provider is enabled.
+     */
     is_enabled: boolean
   }
+  /**
+   * The shipping option's amount.
+   */
   amount: number
 }

packages/core/types/src/http/order/common.ts

@@ -8,208 +8,706 @@ import { BaseProduct, BaseProductVariant } from "../product/common"
 import { BaseReturn } from "../return/common"
 
 export interface BaseOrderSummary {
+  /**
+   * The total of the order including taxes and promotions.
+   */
   total: number
+  /**
+   * The total of the order excluding taxes, including promotions.
+   */
   subtotal: number
+  /**
+   * The tax totals of the order including promotions.
+   */
   total_tax: number
+  /**
+   * The total ordered amount.
+   */
   ordered_total: number
+  /**
+   * The total fulfilled amount.
+   */
   fulfilled_total: number
+  /**
+   * The total amount of returned items.
+   */
   returned_total: number
+  /**
+   * The total amount of the items requested to be returned.
+   */
   return_request_total: number
+  /**
+   * The total amount of the items removed from the order.
+   */
   write_off_total: number
+  /**
+   * The total amount paid.
+   */
   paid_total: number
+  /**
+   * The total amount refunded
+   */
   refunded_total: number
 }
 
 export interface BaseOrderAdjustmentLine {
+  /**
+   * The adjustment line's ID.
+   */
   id: string
+  /**
+   * The adjustment's promotion code.
+   */
   code?: string
+  /**
+   * The adjustment's amount.
+   */
   amount: number
+  /**
+   * The ID of the order this adjustment line belongs to.
+   */
   order_id: string
+  /**
+   * The adjustment's description.
+   */
   description?: string
+  /**
+   * The ID of the applied promotion.
+   */
   promotion_id?: string
+  /**
+   * The ID of the associated provider.
+   */
   provider_id?: string
+  /**
+   * The date the adjustment was created.
+   */
   created_at: Date | string
+  /**
+   * The date the adjustment was updated.
+   */
   updated_at: Date | string
 }
 
 export interface BaseOrderShippingMethodAdjustment
   extends BaseOrderAdjustmentLine {
+  /**
+   * The associated shipping method's details.
+   */
   shipping_method: BaseOrderShippingMethod
+  /**
+   * The associated shipping method's ID.
+   */
   shipping_method_id: string
 }
 
 export interface BaseOrderLineItemAdjustment extends BaseOrderAdjustmentLine {
+  /**
+   * The associated item's details.
+   */
   item: BaseOrderLineItem
+  /**
+   * The associated item's ID.
+   */
   item_id: string
 }
 
 export interface BaseOrderTaxLine {
+  /**
+   * The ID of thet ax line.
+   */
   id: string
+  /**
+   * The tax rate's description.
+   */
   description?: string
+  /**
+   * The ID of the associated tax rate.
+   */
   tax_rate_id?: string
+  /**
+   * The associated tax rate's code.
+   */
   code: string
+  /**
+   * The rate charged.
+   */
   rate: number
+  /**
+   * The ID of the tax provider used.
+   */
   provider_id?: string
+  /**
+   * The date the tax line was created.
+   */
   created_at: Date | string
+  /**
+   * The date the tax line was updated.
+   */
   updated_at: Date | string
 }
 
 export interface BaseOrderShippingMethodTaxLine extends BaseOrderTaxLine {
+  /**
+   * The shipping method's details.
+   */
   shipping_method: BaseOrderShippingMethod
+  /**
+   * The shipping method's ID.
+   */
   shipping_method_id: string
+  /**
+   * The shipping method's total including taxes and promotions.
+   */
   total: number
+  /**
+   * The shipping method's total excluding taxes, including promotions.
+   */
   subtotal: number
 }
 
 export interface BaseOrderLineItemTaxLine extends BaseOrderTaxLine {
+  /**
+   * The item's details.
+   */
   item: BaseOrderLineItem
+  /**
+   * The item's ID.
+   */
   item_id: string
+  /**
+   * The item's total including taxes and promotions.
+   */
   total: number
+  /**
+   * The item's total excluding taxes, including promotions.
+   */
   subtotal: number
 }
 
 export interface BaseOrderAddress {
+  /**
+   * The address's ID.
+   */
   id: string
+  /**
+   * The ID of the customer this address belongs to.
+   */
   customer_id?: string
+  /**
+   * The address's first name.
+   */
   first_name?: string
+  /**
+   * The address's last name.
+   */
   last_name?: string
+  /**
+   * The address's phone.
+   */
   phone?: string
+  /**
+   * The address's company.
+   */
   company?: string
+  /**
+   * The address's first line.
+   */
   address_1?: string
+  /**
+   * The address's second line.
+   */
   address_2?: string
+  /**
+   * The address's city.
+   */
   city?: string
+  /**
+   * The address's country code.
+   * 
+   * @example us
+   */
   country_code?: string
+  /**
+   * The address's province.
+   */
   province?: string
+  /**
+   * The address's postal code.
+   */
   postal_code?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The date the address was created.
+   */
   created_at: Date | string
+  /**
+   * The date the address was updated.
+   */
   updated_at: Date | string
 }
 
 export interface BaseOrderShippingMethod {
+  /**
+   * The shipping method's ID.
+   */
   id: string
+  /**
+   * The ID of the order this shipping method belongs to.
+   */
   order_id: string
+  /**
+   * The shipping method's name.
+   */
   name: string
+  /**
+   * The shipping method's description.
+   */
   description?: string
+  /**
+   * The shipping method's amount.
+   */
   amount: number
+  /**
+   * Whether the shipping method's amount includes taxes.
+   */
   is_tax_inclusive: boolean
+  /**
+   * The ID of the shipping option this method was created from.
+   */
   shipping_option_id: string | null
+  /**
+   * Data relevant for the fulfillment provider handling the shipping.
+   * 
+   * Learn more in [this guide](https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
   data: Record<string, unknown> | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The shipping method's tax lines.
+   */
   tax_lines?: BaseOrderShippingMethodTaxLine[]
+  /**
+   * The shipping method's adjustments.
+   */
   adjustments?: BaseOrderShippingMethodAdjustment[]
+  /**
+   * The total of the shipping method including taxes, excluding promotions.
+   */
   original_total: number
+  /**
+   * The total of the shipping method excluding taxes, including promotions.
+   */
   original_subtotal: number
+  /**
+   * The tax total of the shipping method excluding promotions.
+   */
   original_tax_total: number
+  /**
+   * The total of the shipping method including taxes and promotions.
+   */
   total: number
+  /**
+   * The shipping method's action details.
+   */
   detail?: BaseOrderShippingDetail
+  /**
+   * The total of the shipping method excluding taxes, including promotions.
+   */
   subtotal: number
+  /**
+   * The tax total of the shipping method including promotions.
+   */
   tax_total: number
+  /**
+   * The total discounted amount.
+   */
   discount_total: number
+  /**
+   * The tax total of the shipping method's discounted amount.
+   */
   discount_tax_total: number
+  /**
+   * The date the shipping method was created.
+   */
   created_at: Date | string
+  /**
+   * The date the shipping method was updated.
+   */
   updated_at: Date | string
 }
 
 export interface BaseOrderLineItem {
+  /**
+   * The item's ID.
+   */
   id: string
+  /**
+   * The item's title.
+   */
   title: string
+  /**
+   * The item's subtitle.
+   */
   subtitle: string | null
+  /**
+   * The URL of the item's thumbnail.
+   */
   thumbnail: string | null
+  /**
+   * The item's associated variant.
+   */
   variant?: BaseProductVariant | null
+  /**
+   * The ID of the associated variant.
+   */
   variant_id: string | null
+  /**
+   * The item's associated product..
+   */
   product?: BaseProduct
+  /**
+   * The ID of the associated product.
+   */
   product_id: string | null
+  /**
+   * The associated product's title.
+   */
   product_title: string | null
+  /**
+   * The associated product's description.
+   */
   product_description: string | null
+  /**
+   * The associated product's subtitle.
+   */
   product_subtitle: string | null
+  /**
+   * The ID of the associated product's type.
+   */
   product_type: string | null
+  /**
+   * The ID of the associated product's collection.
+   */
   product_collection: string | null
+  /**
+   * The associated product's handle.
+   */
   product_handle: string | null
+  /**
+   * The associated variant's SKU.
+   */
   variant_sku: string | null
+  /**
+   * The associated variant's barcode.
+   */
   variant_barcode: string | null
+  /**
+   * The associated variant's title.
+   */
   variant_title: string | null
+  /**
+   * The associated variant's values for the product's options.
+   */
   variant_option_values: Record<string, unknown> | null
+  /**
+   * Whether the item requires shipping.
+   */
   requires_shipping: boolean
+  /**
+   * Whether discounts can be applied on the item.
+   */
   is_discountable: boolean
+  /**
+   * Whether the item's price includes taxes.
+   */
   is_tax_inclusive: boolean
+  /**
+   * The original price of the item before a promotion or sale.
+   */
   compare_at_unit_price?: number
+  /**
+   * The price of a single quantity of the item.
+   */
   unit_price: number
+  /**
+   * The item's quantity.
+   */
   quantity: number
+  /**
+   * The item's tax lines.
+   */
   tax_lines?: BaseOrderLineItemTaxLine[]
+  /**
+   * The item's adjustments.
+   */
   adjustments?: BaseOrderLineItemAdjustment[]
+  /**
+   * The item's action details.
+   */
   detail: BaseOrderItemDetail
+  /**
+   * The date the item was created.
+   */
   created_at: Date
+  /**
+   * The date the item was updated.
+   */
   updated_at: Date
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The total of the item including taxes, excluding promotions.
+   */
   original_total: number
+  /**
+   * The total of the item excluding taxes, including promotions.
+   */
   original_subtotal: number
+  /**
+   * The total taxes applied on the item, excluding promotions.
+   */
   original_tax_total: number
+  /**
+   * The total of a single quantity of the the item including taxes and promotions.
+   */
   item_total: number
+  /**
+   * The total of a single quantity of the the item excluding taxes, including promotions.
+   */
   item_subtotal: number
+  /**
+   * The total taxes applied on a single quantity of the item, including promotions.
+   */
   item_tax_total: number
+  /**
+   * The total of the item including taxes and promotions.
+   */
   total: number
+  /**
+   * The total of the item excluding taxes, including promotions.
+   */
   subtotal: number
+  /**
+   * The total taxes of the item, including promotions.
+   */
   tax_total: number
+  /**
+   * The total discount applied on the item.
+   */
   discount_total: number
+  /**
+   * The total taxes applied on the discounted amount.
+   */
   discount_tax_total: number
+  /**
+   * The total amount that can be refunded.
+   */
   refundable_total: number
+  /**
+   * The total amount that can be refunded for a single quantity.
+   */
   refundable_total_per_unit: number
 }
 
 export interface BaseOrderItemDetail {
+  /**
+   * The item detail's ID.
+   */
   id: string
+  /**
+   * The ID of the associated item.
+   */
   item_id: string
+  /**
+   * The associated item.
+   */
   item: BaseOrderLineItem
+  /**
+   * The item's total quantity.
+   */
   quantity: number
+  /**
+   * The item's fulfilled quantity.
+   */
   fulfilled_quantity: number
+  /**
+   * The item's delivered quantity.
+   */
   delivered_quantity: number
+  /**
+   * The item's shipped quantity.
+   */
   shipped_quantity: number
+  /**
+   * The item's quantity that's requested to be returned.
+   */
   return_requested_quantity: number
+  /**
+   * The item's quantity that's received by a return.
+   */
   return_received_quantity: number
+  /**
+   * The item's quantity that's returned but dismissed due to damages or other reasons.
+   */
   return_dismissed_quantity: number
+  /**
+   * The item's quantity removed from the order.
+   */
   written_off_quantity: number
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The date the detail was created.
+   */
   created_at: Date
+  /**
+   * The date the detail was deleted.
+   */
   updated_at: Date
 }
 
 export interface BaseOrderShippingDetail {
+  /**
+   * The shipping details' ID.
+   */
   id: string
+  /**
+   * The ID of the shipping method it belongs to.
+   */
   shipping_method_id: string
+  /**
+   * The shipping method it belongs to.
+   */
   shipping_method: BaseOrderShippingMethod
+  /**
+   * The ID of the associated claim.
+   */
   claim_id?: string
+  /**
+   * The ID of the associated exchange.
+   */
   exchange_id?: string
+  /**
+   * The ID of the associated return.
+   */
   return_id?: string
+  /**
+   * The date the detail was created.
+   */
   created_at: Date
+  /**
+   * The date the detail was updated.
+   */
   updated_at: Date
 }
 
 export interface BaseOrderTransaction {
+  /**
+   * The transaction's ID.
+   */
   id: string
+  /**
+   * The ID of the order this transaction belongs to.
+   */
   order_id: string
+  /**
+   * The transaction's amount.
+   */
   amount: number
+  /**
+   * The transaction's currency code.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * Whether the transaction references a capture or refund.
+   */
   reference: "capture" | "refund"
+  /**
+   * The ID of the capture or refund, depending on the value of {@link reference}.
+   */
   reference_id: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The date the transaction was created.
+   */
   created_at: Date | string
+  /**
+   * The date the transaction was updated.
+   */
   updated_at: Date | string
 }
 
 export interface BaseOrderFulfillment {
+  /**
+   * The fulfillment's ID.
+   */
   id: string
+  /**
+   * The ID of the location the items are fulfilled from.
+   */
   location_id: string
+  /**
+   * The date the fulfillment was packed.
+   */
   packed_at: Date | null
+  /**
+   * The date the fulfillment was shipped.
+   */
   shipped_at: Date | null
+  /**
+   * The date the fulfillment was delivered.
+   */
   delivered_at: Date | null
+  /**
+   * The date the fulfillment was canceled.
+   */
   canceled_at: Date | null
+  /**
+   * Whether the fulfillment requires shipping.
+   */
   requires_shipping: boolean
+  /**
+   * Data necessary for the provider handling the fulfillment.
+   * 
+   * Learn more in [this guide](https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property).
+   */
   data: Record<string, unknown> | null
+  /**
+   * The ID of the fulfillment provider handling this fulfillment.
+   */
   provider_id: string
+  /**
+   * The ID of the associated shipping option.
+   */
   shipping_option_id: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata: Record<string, unknown> | null
+  /**
+   * The date the fulfillment was created.
+   */
   created_at: Date
+  /**
+   * The date the fulfillment was updated.
+   */
   updated_at: Date
 }
 
@@ -236,48 +734,180 @@ type FulfillmentStatus =
   | "canceled"
 
 export interface BaseOrder {
+  /**
+   * The order's ID.
+   */
   id: string
+  /**
+   * The order's version.
+   */
   version: number
+  /**
+   * The ID of the associated region.
+   */
   region_id: string | null
+  /**
+   * The ID of the customer that placed the order.
+   */
   customer_id: string | null
+  /**
+   * The ID of the sales channel the order was placed in.
+   */
   sales_channel_id: string | null
+  /**
+   * The email of the customer that placed the order.
+   */
   email: string | null
+  /**
+   * The order's currency code.
+   * 
+   * @example
+   * usd
+   */
   currency_code: string
+  /**
+   * The order's display ID.
+   */
   display_id?: number
+  /**
+   * The order's shipping address.
+   */
   shipping_address?: BaseOrderAddress | null
+  /**
+   * The order's billing address.
+   */
   billing_address?: BaseOrderAddress | null
+  /**
+   * The order's items.
+   */
   items: BaseOrderLineItem[] | null
+  /**
+   * The order's shipping methods.
+   */
   shipping_methods: BaseOrderShippingMethod[] | null
+  /**
+   * The order's payment collections.
+   */
   payment_collections?: BasePaymentCollection[]
+  /**
+   * The order's payment status.
+   */
   payment_status: PaymentStatus
+  /**
+   * The order's fulfillments.
+   */
   fulfillments?: BaseOrderFulfillment[]
+  /**
+   * The order's fulfillment status.
+   */
   fulfillment_status: FulfillmentStatus
+  /**
+   * The order's transactions.
+   */
   transactions?: BaseOrderTransaction[]
+  /**
+   * The order's summary.
+   */
   summary: BaseOrderSummary
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
+  /**
+   * The date the order was created.
+   */
   created_at: string | Date
+  /**
+   * The date the order was updated.
+   */
   updated_at: string | Date
+  /**
+   * The total of the order's items including taxes, excluding promotions.
+   */
   original_item_total: number
+  /**
+   * The total of the order's items excluding taxes, including promotions.
+   */
   original_item_subtotal: number
+  /**
+   * The tax total applied on the order's items, excluding promotions.
+   */
   original_item_tax_total: number
+  /**
+   * The total of the order's items including taxes and promotions.
+   */
   item_total: number
+  /**
+   * The total of the order's items excluding taxes, including promotions.
+   */
   item_subtotal: number
+  /**
+   * The tax total applied on the order's items, including promotions.
+   */
   item_tax_total: number
+  /**
+   * The total of the order including taxes, excluding promotions.
+   */
   original_total: number
+  /**
+   * The total of the order excluding taxes, including promotions.
+   */
   original_subtotal: number
+  /**
+   * The tax total applied on the order's items, excluding promotions.
+   */
   original_tax_total: number
+  /**
+   * The total of the order including taxes and promotions.
+   */
   total: number
+  /**
+   * The total of the order excluding taxes, including promotions.
+   */
   subtotal: number
+  /**
+   * The tax total applied on the order's items, including promotions.
+   */
   tax_total: number
+  /**
+   * The total amount discounted.
+   */
   discount_total: number
+  /**
+   * The tax total applied on the order's discounted amount.
+   */
   discount_tax_total: number
+  /**
+   * The total gift card amount.
+   */
   gift_card_total: number
+  /**
+   * The tax total applied on the order's gift card amount.
+   */
   gift_card_tax_total: number
+  /**
+   * The total of the order's shipping methods including taxes and promotions.
+   */
   shipping_total: number
+  /**
+   * The total of the order's shipping methods excluding taxes, including promotions.
+   */
   shipping_subtotal: number
+  /**
+   * The tax total applied on the order's shipping methods, including promotions.
+   */
   shipping_tax_total: number
+  /**
+   * The total of the order's shipping methods including taxes, excluding promotions.
+   */
   original_shipping_total: number
+  /**
+   * The total of the order's shipping methods excluding taxes, including promotions.
+   */
   original_shipping_subtotal: number
+  /**
+   * The tax total applied on the order's shipping methods, excluding promotions.
+   */
   original_shipping_tax_total: number
 }
 

packages/core/types/src/http/order/store/entities.ts

@@ -18,29 +18,68 @@ import {
 
 export interface StoreOrder
   extends Omit<BaseOrder, "items" | "version" | "transations"> {
+  /**
+   * The order's shipping address.
+   */
   shipping_address?: StoreOrderAddress | null
+  /**
+   * The order's billing address.
+   */
   billing_address?: StoreOrderAddress | null
+  /**
+   * The order's items.
+   */
   items: StoreOrderLineItem[] | null
+  /**
+   * The order's shipping methods.
+   */
   shipping_methods: StoreOrderShippingMethod[] | null
+  /**
+   * The order's payment collections.
+   */
   payment_collections?: StorePaymentCollection[]
+  /**
+   * The order's fulfillments.
+   */
   fulfillments?: StoreOrderFulfillment[]
+  /**
+   * The customer that placed the order.
+   */
   customer?: StoreCustomer
 }
 export interface StoreOrderLineItem
   extends Omit<BaseOrderLineItem, "product" | "variant"> {
+  /**
+   * The associated product variant.
+   */
   variant?: StoreProductVariant
+  /**
+   * The associated product.
+   */
   product?: StoreProduct
+  /**
+   * The item's tax lines.
+   */
   tax_lines?: (BaseOrderLineItemTaxLine & {
     item: StoreOrderLineItem
   })[]
+  /**
+   * The item's adjustments.
+   */
   adjustments?: (BaseOrderLineItemAdjustment & {
     item: StoreOrderLineItem
   })[]
+  /**
+   * The item's action details.
+   */
   detail: BaseOrderItemDetail & {
     item: StoreOrderLineItem
   }
 }
 export interface StoreOrderAddress extends BaseOrderAddress {
+  /**
+   * The address's country.
+   */
   country?: StoreRegionCountry
 }
 export interface StoreOrderShippingMethod extends BaseOrderShippingMethod {

packages/core/types/src/http/order/store/queries.ts

@@ -5,6 +5,12 @@ import { FindParams } from "../../common"
 export interface StoreOrderFilters
   extends FindParams,
     BaseFilterable<StoreOrderFilters> {
+  /**
+   * Filter by order ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by order status(es).
+   */
   status?: OrderStatus | OrderStatus[]
 }

packages/core/types/src/http/order/store/responses.ts

@@ -2,7 +2,15 @@ import { PaginatedResponse } from "../../common"
 import { StoreOrder } from "./entities"
 
 export interface StoreOrderResponse {
+  /**
+   * The order's details.
+   */
   order: StoreOrder
 }
 
-export type StoreOrderListResponse = PaginatedResponse<{ orders: StoreOrder[] }>
+export type StoreOrderListResponse = PaginatedResponse<{ 
+  /**
+   * The list of orders.
+   */
+  orders: StoreOrder[]
+}>

packages/core/types/src/http/payment/common.ts

@@ -23,6 +23,9 @@ export type BasePaymentSessionStatus =
   | "canceled"
 
 export interface BasePaymentProvider {
+  /**
+   * The provider's ID.
+   */
   id: string
 }
 

packages/core/types/src/http/payment/store/entities.ts

@@ -6,9 +6,18 @@ import {
 
 export interface StorePaymentProvider extends BasePaymentProvider {}
 export interface StorePaymentCollection extends BasePaymentCollection {
+  /**
+   * The payment collection's sessions.
+   */
   payment_sessions?: StorePaymentSession[]
+  /**
+   * The providers used for the payment collection's sessions.
+   */
   payment_providers: StorePaymentProvider[]
 }
 export interface StorePaymentSession extends BasePaymentSession {
+  /**
+   * The payment collection that the session belongs to.
+   */
   payment_collection?: StorePaymentCollection
 }

packages/core/types/src/http/payment/store/payloads.ts

@@ -1,3 +1,22 @@
 export interface StoreCreatePaymentCollection {
   cart_id: string
 }
+
+export interface StoreInitializePaymentSession {
+  /**
+   * The ID of the provider to initialize a payment session
+   * for.
+   */
+  provider_id: string
+  /**
+   * The payment's context, such as the customer or address details. if the customer is logged-in, 
+   * the customer id is set in the context under a `customer.id` property.
+   */
+  context?: Record<string, unknown>
+  /**
+   * Any data necessary for the payment provider to process the payment.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/v2/resources/commerce-modules/payment/payment-session#data-property).
+   */
+  data?: Record<string, unknown>
+}

packages/core/types/src/http/payment/store/queries.ts

@@ -4,6 +4,9 @@ import {
 } from "../common"
 
 export interface StorePaymentProviderFilters {
+  /**
+   * The ID of the region to retrieve its payment providers.
+   */
   region_id: string
 }
 export interface StorePaymentCollectionFilters

packages/core/types/src/http/payment/store/responses.ts

@@ -2,9 +2,15 @@ import { PaginatedResponse } from "../../common"
 import { StorePaymentCollection, StorePaymentProvider } from "./entities"
 
 export interface StorePaymentCollectionResponse {
+  /**
+   * The payment collection's details.
+   */
   payment_collection: StorePaymentCollection
 }
 
 export type StorePaymentProviderListResponse = PaginatedResponse<{
+  /**
+   * The paginated list of providers.
+   */
   payment_providers: StorePaymentProvider[]
 }>

packages/core/types/src/http/product-category/common.ts

@@ -3,42 +3,136 @@ import { FindParams, SelectParams } from "../common"
 import { BaseProduct } from "../product/common"
 
 export interface BaseProductCategory {
+  /**
+   * The category's ID.
+   */
   id: string
+  /**
+   * The category's name.
+   */
   name: string
+  /**
+   * The category's description.
+   */
   description: string
+  /**
+   * The category's handle.
+   */
   handle: string
+  /**
+   * Whether the category is active.
+   */
   is_active: boolean
+  /**
+   * Whether the category is internal.
+   */
   is_internal: boolean
+  /**
+   * The category's ranking among sibling categories.
+   */
   rank: number | null
+  /**
+   * The ID of the category's parent.
+   */
   parent_category_id: string | null
+  /**
+   * The category's parent.
+   */
   parent_category: BaseProductCategory | null
+  /**
+   * The category's children.
+   */
   category_children: BaseProductCategory[]
+  /**
+   * The category's products.
+   */
   products?: BaseProduct[]
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
+  /**
+   * The date the category was created.
+   */
   created_at: string
+  /**
+   * The date the category was updated.
+   */
   updated_at: string
+  /**
+   * The date the category was deleted.
+   */
   deleted_at: string | null
 }
 
 export interface BaseProductCategoryListParams
   extends FindParams,
     BaseFilterable<BaseProductCategoryListParams> {
+  /**
+   * A query or keywords to search the category's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by the category's ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by the category's name(s).
+   */
   name?: string | string[]
+  /**
+   * Filter by the category's description(s).
+   */
   description?: string | string[]
+  /**
+   * Retrieve the child categories of the specified parent ID(s).
+   */
   parent_category_id?: string | string[] | null
+  /**
+   * Filter by the category's handle(s).
+   */
   handle?: string | string[]
+  /**
+   * Filter by whether the category is active.
+   */
   is_active?: boolean
+  /**
+   * Filter by whether the category is internal.
+   */
   is_internal?: boolean
+  /**
+   * Whether to retrieve the child categories. If enabled, the child categories are
+   * retrieved in the `category_children` field.
+   */
   include_descendants_tree?: boolean
+  /**
+   * Whether to retrieve the parent category. If enabled, the parent category is
+   * retrieved in the `parent_category` field.
+   */
   include_ancestors_tree?: boolean
+  /**
+   * Apply filters on the category's creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the category's update date.
+   */
   updated_at?: OperatorMap<string>
+  /**
+   * Apply filters on the category's deletion date.
+   */
   deleted_at?: OperatorMap<string>
 }
 
 export interface BaseProductCategoryParams extends SelectParams {
+  /**
+   * Whether to retrieve the parent category. If enabled, the parent category is
+   * retrieved in the `parent_category` field.
+   */
   include_ancestors_tree?: boolean
+  /**
+   * Whether to retrieve the child categories. If enabled, the child categories are
+   * retrieved in the `category_children` field.
+   */
   include_descendants_tree?: boolean
 }

packages/core/types/src/http/product-category/store/entities.ts

@@ -10,7 +10,16 @@ export interface StoreProductCategory
     | "parent_category"
     | "category_children"
   > {
+  /**
+   * The category's products.
+   */
   products?: StoreProduct[]
+  /**
+   * The parent category.
+   */
   parent_category: StoreProductCategory | null
+  /**
+   * The category's children.
+   */
   category_children: StoreProductCategory[]
 }

packages/core/types/src/http/product-category/store/queries.ts

@@ -4,6 +4,6 @@ import {
 } from "../common"
 
 export interface StoreProductCategoryListParams
-  extends Omit<BaseProductCategoryListParams, "is_internal" | "is_active"> {}
+  extends Omit<BaseProductCategoryListParams, "is_internal" | "is_active" | "deleted_at"> {}
 
 export interface StoreProductCategoryParams extends BaseProductCategoryParams {}

packages/core/types/src/http/product-category/store/responses.ts

@@ -2,10 +2,16 @@ import { PaginatedResponse } from "../../common"
 import { StoreProductCategory } from "./entities"
 
 export interface StoreProductCategoryResponse {
+  /**
+   * The category's details.
+   */
   product_category: StoreProductCategory
 }
 
 export interface StoreProductCategoryListResponse
   extends PaginatedResponse<{
+    /**
+     * The paginated list of categories.
+     */
     product_categories: StoreProductCategory[]
   }> {}

packages/core/types/src/http/product/common.ts

@@ -8,77 +8,276 @@ import { BaseProductType } from "../product-type/common"
 
 export type ProductStatus = "draft" | "proposed" | "published" | "rejected"
 export interface BaseProduct {
+  /**
+   * The product's ID.
+   */
   id: string
+  /**
+   * The product's title.
+   */
   title: string
+  /**
+   * The product's handle.
+   */
   handle: string
+  /**
+   * The product's subtitle.
+   */
   subtitle: string | null
+  /**
+   * The product's description.
+   */
   description: string | null
+  /**
+   * Whether the product is a gift card.
+   */
   is_giftcard: boolean
+  /**
+   * The product's status.
+   */
   status: ProductStatus
+  /**
+   * The product's thumbnail.
+   */
   thumbnail: string | null
+  /**
+   * The product's width.
+   */
   width: number | null
+  /**
+   * The product's weight.
+   */
   weight: number | null
+  /**
+   * The product's length.
+   */
   length: number | null
+  /**
+   * The product's height.
+   */
   height: number | null
+  /**
+   * The product's origin country.
+   */
   origin_country: string | null
+  /**
+   * The product's HS code.
+   */
   hs_code: string | null
+  /**
+   * The product's MID code.
+   */
   mid_code: string | null
+  /**
+   * The product's material.
+   */
   material: string | null
+  /**
+   * The product's collection.
+   */
   collection?: BaseCollection | null
+  /**
+   * The ID of the associated product collection.
+   */
   collection_id: string | null
+  /**
+   * The product's categories.
+   */
   categories?: BaseProductCategory[] | null
+  /**
+   * The product's type.
+   */
   type?: BaseProductType | null
+  /**
+   * The ID of the associated product type.
+   */
   type_id: string | null
+  /**
+   * The product's tags.
+   */
   tags?: BaseProductTag[] | null
+  /**
+   * The product's variants.
+   */
   variants: BaseProductVariant[] | null
+  /**
+   * The product's options.
+   */
   options: BaseProductOption[] | null
+  /**
+   * The product's images.
+   */
   images: BaseProductImage[] | null
+  /**
+   * Whether the product is discountable.
+   */
   discountable: boolean
+  /**
+   * The ID of the product in external systems.
+   */
   external_id: string | null
+  /**
+   * The date the product was created.
+   */
   created_at: string | null
+  /**
+   * The date the product was update.
+   */
   updated_at: string | null
+  /**
+   * The date the product was deleted.
+   */
   deleted_at: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 
 export interface BaseProductVariant {
+  /**
+   * The variant's ID.
+   */
   id: string
+  /**
+   * The variant's title.
+   */
   title: string | null
+  /**
+   * The variant's SKU.
+   */
   sku: string | null
+  /**
+   * The variant's barcode.
+   */
   barcode: string | null
+  /**
+   * The variant's EAN.
+   */
   ean: string | null
+  /**
+   * The variant's UPC.
+   */
   upc: string | null
+  /**
+   * Whether the variant can be ordered even if it's out of stock.
+   */
   allow_backorder: boolean | null
+  /**
+   * Whether Medusa manages the variant's inventory. If disabled, the variant
+   * is always considered in stock.
+   */
   manage_inventory: boolean | null
+  /**
+   * The variant's inventory quantity if `manage_inventory` is enabled.
+   */
   inventory_quantity?: number
+  /**
+   * The variant's HS code.
+   */
   hs_code: string | null
+  /**
+   * The variant's origin country.
+   */
   origin_country: string | null
+  /**
+   * The variant's MID code.
+   */
   mid_code: string | null
+  /**
+   * The variant's material.
+   */
   material: string | null
+  /**
+   * The variant's weight.
+   */
   weight: number | null
+  /**
+   * The variant's length.
+   */
   length: number | null
+  /**
+   * The variant's height.
+   */
   height: number | null
+  /**
+   * The variant's width.
+   */
   width: number | null
+  /**
+   * The variant's ranking among its siblings.
+   */
   variant_rank?: number | null
+  /**
+   * The variant's values for the product's options.
+   */
   options: BaseProductOptionValue[] | null
+  /**
+   * The variant's product.
+   */
   product?: BaseProduct | null
+  /**
+   * The ID of the product that the variant belongs to.
+   */
   product_id?: string
+  /**
+   * The variant's calculated price for the provided context.
+   */
   calculated_price?: BaseCalculatedPriceSet
+  /**
+   * The date the variant was created.
+   */
   created_at: string
+  /**
+   * The date the variant was updated.
+   */
   updated_at: string
+  /**
+   * The date the variant was deleted.
+   */
   deleted_at: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
 }
 
 export interface BaseProductOption {
+  /**
+   * The option's ID.
+   */
   id: string
+  /**
+   * The option's title.
+   */
   title: string
+  /**
+   * The product that the option belongs to.
+   */
   product?: BaseProduct | null
+  /**
+   * The ID of the product that the option belongs to.
+   */
   product_id?: string | null
+  /**
+   * The option's values.
+   */
   values?: BaseProductOptionValue[]
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
+  /**
+   * The date the option was created.
+   */
   created_at?: string
+  /**
+   * The date the option was updated.
+   */
   updated_at?: string
+  /**
+   * The date the option was deleted.
+   */
   deleted_at?: string | null
 }
 
@@ -92,33 +291,102 @@ export interface BaseProductImage {
 }
 
 export interface BaseProductOptionValue {
+  /**
+   * The option value's ID.
+   */
   id: string
+  /**
+   * The option's value.
+   */
   value: string
+  /**
+   * The option's details.
+   */
   option?: BaseProductOption | null
+  /**
+   * The ID of the option.
+   */
   option_id?: string | null
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown> | null
+  /**
+   * The date the option value was created.
+   */
   created_at?: string
+  /**
+   * The date the option value was updated.
+   */
   updated_at?: string
+  /**
+   * The date the option value was deleted.
+   */
   deleted_at?: string | null
 }
 
 export interface BaseProductListParams
   extends FindParams,
     BaseFilterable<BaseProductListParams> {
+  /**
+   * A query or keywords to search the searchable fields by.
+   */
   q?: string
+  /**
+   * Filter the product by status(es).
+   */
   status?: ProductStatus | ProductStatus[]
+  /**
+   * Filter the product by the sales channel(s) it belongs to.
+   */
   sales_channel_id?: string | string[]
+  /**
+   * Filter by the product's title(s).
+   */
   title?: string | string[]
+  /**
+   * Filter by the product's handle(s).
+   */
   handle?: string | string[]
+  /**
+   * Filter by the product's id(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by whether the product is a gift card.
+   */
   is_giftcard?: boolean
+  /**
+   * Filter by the product's tag(s).
+   */
   tags?: string | string[]
+  /**
+   * Filter by the product's type(s).
+   */
   type_id?: string | string[]
+  /**
+   * Filter by the product's category(s).
+   */
   category_id?: string | string[]
+  /**
+   * Filter by the product's category(s).
+   */
   categories?: string | string[]
+  /**
+   * Filter by the product's collection(s).
+   */
   collection_id?: string | string[]
+  /**
+   * Apply filers on the product's creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filers on the product's update date.
+   */
   updated_at?: OperatorMap<string>
+  /**
+   * Apply filers on the product's deletion date.
+   */
   deleted_at?: OperatorMap<string>
 }
 

packages/core/types/src/http/product/store/entitites.ts

@@ -16,27 +16,63 @@ export interface StoreProduct
     BaseProduct,
     "categories" | "sales_channels" | "variants" | "options" | "collection"
   > {
+  /**
+   * The product's collection.
+   */
   collection?: StoreCollection | null
+  /**
+   * The product's categories.
+   */
   categories?: StoreProductCategory[] | null
+  /**
+   * The product's variants.
+   */
   variants: StoreProductVariant[] | null
+  /**
+   * The product's types.
+   */
   type?: StoreProductType | null
+  /**
+   * The product's tags.
+   */
   tags?: StoreProductTag[] | null
+  /**
+   * The product's options.
+   */
   options: StoreProductOption[] | null
+  /**
+   * The product's images.
+   */
   images: StoreProductImage[] | null
 }
 export interface StoreProductVariant
   extends Omit<BaseProductVariant, "product" | "options"> {
+  /**
+   * The variant's values for the product's options.
+   */
   options: StoreProductOptionValue[] | null
+  /**
+   * The variant's product.
+   */
   product?: StoreProduct | null
 }
 export interface StoreProductOption
   extends Omit<BaseProductOption, "product" | "values"> {
+  /**
+   * The product the option belongs to.
+   */
   product?: StoreProduct | null
+  /**
+   * The option's values.
+   */
   values?: StoreProductOptionValue[]
 }
 export interface StoreProductImage extends BaseProductImage {}
 export interface StoreProductOptionValue
   extends Omit<BaseProductOptionValue, "option"> {
+  /**
+   * The product's option.
+   */
   option?: StoreProductOption | null
 }
 export type StoreProductStatus = ProductStatus

packages/core/types/src/http/product/store/queries.ts

@@ -7,11 +7,28 @@ import {
 export interface StoreProductOptionParams extends BaseProductOptionParams {}
 export interface StoreProductVariantParams extends BaseProductVariantParams {}
 export interface StoreProductParams
-  extends Omit<BaseProductListParams, "tags" | "status" | "categories"> {
+  extends Omit<BaseProductListParams, "tags" | "status" | "categories" | "deleted_at"> {
+  /**
+   * Filter by the product's tag(s).
+   */
   tag_id?: string | string[]
-  // The region ID and currency_code are not params, but are used for the pricing context. Maybe move to separate type definition.
+  /**
+   * The ID of the region the products are being viewed from. This is required if you're retrieving product variant prices with taxes.
+   * 
+   * @privateRemarks
+   * The region ID and currency_code are not params, but are used for the pricing context. Maybe move to separate type definition.
+   */
   region_id?: string
+  /**
+   * The currency code to retrieve prices in.
+   */
   currency_code?: string
+  /**
+   * Filter by the product's variants.
+   */
   variants?: Pick<StoreProductVariantParams, "options">
+  /**
+   * The province the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
+   */
   province?: string
 }

packages/core/types/src/http/product/store/responses.ts

@@ -2,9 +2,15 @@ import { PaginatedResponse } from "../../common"
 import { StoreProduct } from "../store"
 
 export interface StoreProductResponse {
+  /**
+   * The product's details.
+   */
   product: StoreProduct
 }
 
 export type StoreProductListResponse = PaginatedResponse<{
+  /**
+   * The list of products.
+   */
   products: StoreProduct[]
 }>

packages/core/types/src/http/region/common.ts

@@ -2,32 +2,101 @@ import { BaseFilterable, OperatorMap } from "../../dal"
 import { AdminPaymentProvider } from "../payment"
 
 export interface BaseRegion {
+  /**
+   * The region's ID.
+   */
   id: string
+  /**
+   * The region's name.
+   */
   name: string
+  /**
+   * The region's currency code.
+   */
   currency_code: string
+  /**
+   * Whether taxes are calculated automatically in the region.
+   */
   automatic_taxes?: boolean
+  /**
+   * The countries that belong to the region.
+   */
   countries?: BaseRegionCountry[]
+  /**
+   * The payment providers enabled in the region.
+   */
   payment_providers?: AdminPaymentProvider[]
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, any> | null
+  /**
+   * The date the region was created.
+   */
   created_at?: string
+  /**
+   * The date the region was updated.
+   */
   updated_at?: string
 }
 
 export interface BaseRegionCountry {
+  /**
+   * The country's ID.
+   */
   id: string
+  /**
+   * The country's ISO 2 code.
+   * 
+   * @example us
+   */
   iso_2?: string
+  /**
+   * The country's ISO 3 code.
+   * 
+   * @example usa
+   */
   iso_3?: string
+  /**
+   * The country's num code.
+   * 
+   * @example 840
+   */
   num_code?: string
+  /**
+   * The country's name.
+   */
   name?: string
+  /**
+   * The country's name used for display.
+   */
   display_name?: string
 }
 
 export interface BaseRegionFilters extends BaseFilterable<BaseRegionFilters> {
+  /**
+   * A query or keywords to search a region's searchable fields by.
+   */
   q?: string
+  /**
+   * Filter by region ID(s).
+   */
   id?: string[] | string | OperatorMap<string | string[]>
+  /**
+   * Filter by region name(s).
+   */
   name?: string | string[]
+  /**
+   * Filter by currency code(s).
+   */
   currency_code?: string | string[]
+  /**
+   * Apply filters on the region's creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the region's update date.
+   */
   updated_at?: OperatorMap<string>
 }
 

packages/core/types/src/http/region/store/responses.ts

@@ -2,9 +2,15 @@ import { PaginatedResponse } from "../../common"
 import { StoreRegion } from "./entities"
 
 export type StoreRegionResponse = {
+  /**
+   * The region's details.
+   */
   region: StoreRegion
 }
 
 export type StoreRegionListResponse = PaginatedResponse<{
+  /**
+   * The paginated list of regions.
+   */
   regions: StoreRegion[]
 }>

packages/core/types/src/http/shipping-option/store/queries.ts

@@ -4,5 +4,13 @@ import { FindParams } from "../../common"
 export interface StoreGetShippingOptionList
   extends FindParams,
     BaseFilterable<StoreGetShippingOptionList> {
+  /**
+   * The ID of the cart to retrieve the shipping options that
+   * can be applied on it.
+   */
   cart_id: string
+  /**
+   * Whether to retrieve shipping options used for returns.
+   */
+  is_return?: boolean
 }

packages/core/types/src/http/shipping-option/store/responses.ts

@@ -1,5 +1,5 @@
-import { StoreShippingOption } from "."
+import { StoreCartShippingOption } from "../../fulfillment"
 
 export interface StoreShippingOptionListResponse {
-  shipping_options: StoreShippingOption[]
+  shipping_options: StoreCartShippingOption[]
 }

packages/medusa/src/api/store/collections/validators.ts

@@ -21,7 +21,6 @@ export const StoreGetCollectionsParams = createFindParams({
     handle: z.union([z.string(), z.array(z.string())]).optional(),
     created_at: createOperatorMap().optional(),
     updated_at: createOperatorMap().optional(),
-    deleted_at: createOperatorMap().optional(),
     $and: z.lazy(() => StoreGetCollectionsParams.array()).optional(),
     $or: z.lazy(() => StoreGetCollectionsParams.array()).optional(),
   })

packages/medusa/src/api/store/payment-collections/[id]/payment-sessions/route.ts

@@ -3,12 +3,11 @@ import {
   AuthenticatedMedusaRequest,
   MedusaResponse,
 } from "@medusajs/framework/http"
-import { StoreCreatePaymentSessionType } from "../../validators"
 import { refetchPaymentCollection } from "../../helpers"
 import { HttpTypes } from "@medusajs/framework/types"
 
 export const POST = async (
-  req: AuthenticatedMedusaRequest<StoreCreatePaymentSessionType>,
+  req: AuthenticatedMedusaRequest<HttpTypes.StoreInitializePaymentSession>,
   res: MedusaResponse<HttpTypes.StorePaymentCollectionResponse>
 ) => {
   const collectionId = req.params.id