From fa15db453853c069f516867e87fb30d6bf00e448 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 21 Oct 2024 11:03:33 +0300 Subject: [PATCH] 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 | 161 ++- packages/core/js-sdk/src/store/index.ts | 1055 ++++++++++++++++- packages/core/js-sdk/src/types.ts | 10 +- .../types/src/http/cart/store/entities.ts | 39 + .../types/src/http/cart/store/payloads.ts | 74 ++ .../types/src/http/cart/store/responses.ts | 28 + .../core/types/src/http/collection/common.ts | 46 +- .../src/http/collection/store/entities.ts | 3 + .../src/http/collection/store/queries.ts | 2 - .../src/http/collection/store/responses.ts | 6 + .../core/types/src/http/common/request.ts | 17 + .../core/types/src/http/common/response.ts | 9 + .../core/types/src/http/customer/common.ts | 240 ++++ .../types/src/http/customer/store/entities.ts | 3 + .../src/http/customer/store/responses.ts | 13 +- .../types/src/http/fulfillment/store/index.ts | 56 +- packages/core/types/src/http/order/common.ts | 630 ++++++++++ .../types/src/http/order/store/entities.ts | 39 + .../types/src/http/order/store/queries.ts | 6 + .../types/src/http/order/store/responses.ts | 10 +- .../core/types/src/http/payment/common.ts | 3 + .../types/src/http/payment/store/entities.ts | 9 + .../types/src/http/payment/store/payloads.ts | 19 + .../types/src/http/payment/store/queries.ts | 3 + .../types/src/http/payment/store/responses.ts | 6 + .../types/src/http/product-category/common.ts | 94 ++ .../http/product-category/store/entities.ts | 9 + .../http/product-category/store/queries.ts | 2 +- .../http/product-category/store/responses.ts | 6 + .../core/types/src/http/product/common.ts | 268 +++++ .../types/src/http/product/store/entitites.ts | 36 + .../types/src/http/product/store/queries.ts | 21 +- .../types/src/http/product/store/responses.ts | 6 + packages/core/types/src/http/region/common.ts | 69 ++ .../types/src/http/region/store/responses.ts | 6 + .../src/http/shipping-option/store/queries.ts | 8 + .../http/shipping-option/store/responses.ts | 4 +- .../src/api/store/collections/validators.ts | 1 - .../[id]/payment-sessions/route.ts | 3 +- 39 files changed, 2945 insertions(+), 75 deletions(-) diff --git a/packages/core/js-sdk/src/auth/index.ts b/packages/core/js-sdk/src/auth/index.ts index a57f0290dfd03..6131c6e46636d 100644 --- a/packages/core/js-sdk/src/auth/index.ts +++ b/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") { diff --git a/packages/core/js-sdk/src/store/index.ts b/packages/core/js-sdk/src/store/index.ts index 33ca17da71743..6fd743da3aa2d 100644 --- a/packages/core/js-sdk/src/store/index.ts +++ b/packages/core/js-sdk/src/store/index.ts @@ -1,37 +1,127 @@ import { FindParams, HttpTypes, - PaginatedResponse, SelectParams, } from "@medusajs/types" import { Client } from "../client" import { ClientHeaders } from "../types" export class Store { + /** + * @ignore + */ private client: Client + /** + * @ignore + */ constructor(client: Client) { this.client = client } public region = { + /** + * This method retrieves the paginated list of regions in the store. It sends a request to the + * [List Regions API route](https://docs.medusajs.com/v2/api/store#regions_getregions). + * + * Related guide: [How to list regions in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/regions/list). + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request + * @returns The paginated list of regions. + * + * @example + * To retrieve the list of regions: + * + * ```ts + * sdk.store.region.list() + * .then(({ regions, count, limit, offset }) => { + * console.log(regions) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.region.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ regions, count, limit, offset }) => { + * console.log(regions) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each region: + * + * ```ts + * sdk.store.region.list({ + * fields: "id,*countries" + * }) + * .then(({ regions, count, limit, offset }) => { + * console.log(regions) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ list: async ( query?: FindParams & HttpTypes.StoreRegionFilters, headers?: ClientHeaders ) => { return this.client.fetch< - PaginatedResponse<{ regions: HttpTypes.StoreRegion[] }> + HttpTypes.StoreRegionListResponse >(`/store/regions`, { query, headers, }) }, + /** + * This method retrieves a region by its ID. It sends a request to the [Get Region](https://docs.medusajs.com/v2/api/store#regions_getregionsid) + * API route. + * + * Related guide: [Store and retrieve regions in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/regions/store-retrieve-region). + * + * @param id - The region's ID. + * @param query - Configure the fields to retrieve in the region. + * @param headers - Headers to pass in the request + * @returns The region. + * + * @example + * To retrieve a region by its ID: + * + * ```ts + * sdk.store.region.retrieve("reg_123") + * .then(({ region }) => { + * console.log(region) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.region.retrieve( + * "reg_123", + * { + * fields: "id,*countries" + * } + * ) + * .then(({ region }) => { + * console.log(region) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieve: async ( id: string, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ region: HttpTypes.StoreRegion }>( + return this.client.fetch( `/store/regions/${id}`, { query, @@ -42,23 +132,105 @@ export class Store { } public collection = { + /** + * This method retrieves a paginated list of product collections. It sends a request to the + * [List Collections](https://docs.medusajs.com/v2/api/store#collections_getcollections) API route. + * + * Related guide: [How to retrieve collections in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/collections/list). + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request + * @returns The paginated list of collections. + * + * @example + * To retrieve the list of collections: + * + * ```ts + * sdk.store.collection.list() + * .then(({ collections, count, limit, offset }) => { + * console.log(collections) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.collection.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ collections, count, limit, offset }) => { + * console.log(collections) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each collection: + * + * ```ts + * sdk.store.collection.list({ + * fields: "id,handle" + * }) + * .then(({ collections, count, limit, offset }) => { + * console.log(collections) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ list: async ( query?: FindParams & HttpTypes.StoreCollectionFilters, headers?: ClientHeaders ) => { return this.client.fetch< - PaginatedResponse<{ collections: HttpTypes.StoreCollection[] }> + HttpTypes.StoreCollectionListResponse >(`/store/collections`, { query, headers, }) }, + /** + * This method retrieves a collection by its ID. It sends a request to the [Get Collection](https://docs.medusajs.com/v2/api/store#collections_getcollectionsid) + * API route. + * + * Related guide: [How to retrieve a collection in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/collections/retrieve). + * + * @param id - The ID of the collection to retrieve. + * @param query - Configure the fields to retrieve in the collection. + * @param headers - Headers to pass in the request + * @returns The collection. + * + * @example + * To retrieve a collection by its ID: + * + * ```ts + * sdk.store.collection.retrieve("pcol_123") + * .then(({ collection }) => { + * console.log(collection) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.collection.retrieve("pcol_123", { + * fields: "id,handle" + * }) + * .then(({ collection }) => { + * console.log(collection) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieve: async ( id: string, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ collection: HttpTypes.StoreCollection }>( + return this.client.fetch( `/store/collections/${id}`, { query, @@ -69,27 +241,107 @@ export class Store { } public category = { + /** + * This method retrieves a paginated list of product categories. It sends a request to the + * [List Categories](https://docs.medusajs.com/v2/api/store#product-categories_getproductcategories) API route. + * + * Related guide: [How to retrieve list of categories in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/categories/list). + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of categoreis. + * + * @example + * To retrieve the list of categoreis: + * + * ```ts + * sdk.store.category.list() + * .then(({ product_categories, count, offset, limit }) => { + * console.log(product_categories) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.category.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ product_categories, count, offset, limit }) => { + * console.log(product_categories) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each category: + * + * ```ts + * sdk.store.category.list({ + * fields: "id,*parent_category" + * }) + * .then(({ product_categories, count, offset, limit }) => { + * console.log(product_categories) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ list: async ( - query?: HttpTypes.StoreProductCategoryParams, + query?: FindParams & HttpTypes.StoreProductCategoryListParams, headers?: ClientHeaders ) => { return this.client.fetch< - PaginatedResponse<{ - product_categories: HttpTypes.StoreProductCategory[] - }> + HttpTypes.StoreProductCategoryListResponse >(`/store/product-categories`, { query, headers, }) }, + /** + * This method retrieves a category by its ID. It sends a request to the + * [Retrieve Product Category](https://docs.medusajs.com/v2/api/store#product-categories_getproductcategoriesid). + * + * Related guide: [How to retrieve a category in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/categories/retrieve). + * + * @param id - The ID of the category to retrieve. + * @param query - Configure the fields to retrieve in the category. + * @param headers - Headers to pass in the request + * @returns The category. + * + * @example + * To retrieve a category by its ID: + * + * ```ts + * sdk.store.category.retrieve("pcat_123") + * .then(({ product_category }) => { + * console.log(product_category) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.category.retrieve("pcat_123", { + * fields: "id,*parent_category" + * }) + * .then(({ product_category }) => { + * console.log(product_category) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieve: async ( id: string, - query?: SelectParams, + query?: HttpTypes.StoreProductCategoryParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ - product_category: HttpTypes.StoreProductCategory - }>(`/store/product-categories/${id}`, { + return this.client.fetch< + HttpTypes.StoreProductCategoryResponse + >(`/store/product-categories/${id}`, { query, headers, }) @@ -97,6 +349,57 @@ export class Store { } public product = { + /** + * This method retrieves a list of products. It sends a request to the + * [List Products API route](https://docs.medusajs.com/v2/api/store#products_getproducts). + * + * Related guides: + * + * - [How to list products in a storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/list). + * - [How to retrieve a product variant's prices in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/price) + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of products. + * + * @example + * To retrieve the list of products: + * + * ```ts + * sdk.store.product.list() + * .then(({ products, count, offset, limit }) => { + * console.log(products) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.product.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ products, count, offset, limit }) => { + * console.log(products) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each product: + * + * ```ts + * sdk.store.product.list({ + * fields: "id,*collection" + * }) + * .then(({ products, count, offset, limit }) => { + * console.log(products) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ list: async ( query?: HttpTypes.StoreProductParams, headers?: ClientHeaders @@ -109,6 +412,43 @@ export class Store { } ) }, + /** + * This method is used to retrieve a product by its ID. It sends a request to the + * [Get Product](https://docs.medusajs.com/v2/api/store#products_getproductsid) API route. + * + * Related guides: + * + * - [How to retrieve a product in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/retrieve). + * - [How to retrieve a product variant's prices in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/products/price) + * + * @param id - The product's ID. + * @param query - Configure the fields to retrieve in the product. + * @param headers - Headers to pass in the request + * @returns The product. + * + * @example + * To retrieve a product by its ID: + * + * ```ts + * sdk.store.product.retrieve("prod_123") + * .then(({ product }) => { + * console.log(product) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.product.retrieve("prod_123", { + * fields: "id,*collection" + * }) + * .then(({ product }) => { + * console.log(product) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieve: async ( id: string, query?: SelectParams, @@ -124,26 +464,68 @@ export class Store { }, } + /** + * Related guides: [How to implement carts in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart). + */ public cart = { + /** + * This method creates a cart. It sends a request to the [Create Cart](https://docs.medusajs.com/v2/api/store#carts_postcarts) + * API route. + * + * Related guide: [How to create a cart in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart/create). + * + * @param body - The details of the cart to create. + * @param query - Configure the fields to retrieve in the cart. + * @param headers - Headers to pass in the request. + * @returns The created cart. + * + * @example + * sdk.store.cart.create({ + * region_id: "reg_123" + * }) + * .then(({ cart }) => { + * console.log(cart) + * }) + */ create: async ( body: HttpTypes.StoreCreateCart, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ cart: HttpTypes.StoreCart }>(`/store/carts`, { + return this.client.fetch(`/store/carts`, { method: "POST", headers, body, query, }) }, + /** + * This method updates a cart. It sends a request to the + * [Update Cart](https://docs.medusajs.com/v2/api/store#carts_postcartsid) API route. + * + * Related guide: [How to update a cart in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart/update). + * + * @param id - The cart's ID. + * @param body - The data to update in the cart. + * @param query - Configure the fields to retrieve in the cart. + * @param headers - Headers to pass in the request. + * @returns The updated cart. + * + * @example + * sdk.store.cart.update("cart_123", { + * region_id: "reg_123" + * }) + * .then(({ cart }) => { + * console.log(cart) + * }) + */ update: async ( id: string, body: HttpTypes.StoreUpdateCart, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ cart: HttpTypes.StoreCart }>( + return this.client.fetch( `/store/carts/${id}`, { method: "POST", @@ -153,12 +535,46 @@ export class Store { } ) }, + /** + * This method retrieves a cart by its ID. It sends a request to the + * [Get Cart](https://docs.medusajs.com/v2/api/store#carts_getcartsid) API route. + * + * Related guide: [How to retrieve a cart in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart/retrieve). + * + * @param id - The cart's ID. + * @param query - Configure the fields to retrieve in the cart. + * @param headers - Headers to pass in the request. + * @returns The cart's details. + * + * @example + * To retrieve a cart by its ID: + * + * ```ts + * sdk.store.cart.retrieve("cart_123") + * .then(({ cart }) => { + * console.log(cart) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.cart.retrieve("cart_123", { + * fields: "id,*items" + * }) + * .then(({ cart }) => { + * console.log(cart) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieve: async ( id: string, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ cart: HttpTypes.StoreCart }>( + return this.client.fetch( `/store/carts/${id}`, { headers, @@ -166,13 +582,34 @@ export class Store { } ) }, + /** + * This methods adds a product variant to the cart as a line item. It sends a request to the + * [Add Line Item](https://docs.medusajs.com/v2/api/store#carts_postcartsidlineitems) API route. + * + * Related guide: [How to manage a cart's line items in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart/manage-items). + * + * @param cartId - The cart's ID. + * @param body - The details of the item to add. + * @param query - Configure the fields to retrieve in the cart. + * @param headers - Headers to pass in the request. + * @returns The cart's details. + * + * @example + * sdk.store.cart.createLineItem("cart_123", { + * variant_id: "variant_123", + * quantity: 1 + * }) + * .then(({ cart }) => { + * console.log(cart) + * }) + */ createLineItem: async ( cartId: string, body: HttpTypes.StoreAddCartLineItem, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ cart: HttpTypes.StoreCart }>( + return this.client.fetch( `/store/carts/${cartId}/line-items`, { method: "POST", @@ -182,6 +619,31 @@ export class Store { } ) }, + /** + * This method updates a line item in a cart. It sends a request to the + * [Update Line Item](https://docs.medusajs.com/v2/api/store#carts_postcartsidlineitemsline_id) API route. + * + * Related guide: [How to manage a cart's line items in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart/manage-items). + * + * @param cartId - The cart's ID. + * @param lineItemId - The line item's ID. + * @param body - The data to update. + * @param query - Configure the fields to retrieve in the cart. + * @param headers - Headers to pass in the request. + * @returns The cart's details. + * + * @example + * sdk.store.cart.updateLineItem( + * "cart_123", + * "li_123", + * { + * quantity: 1 + * } + * ) + * .then(({ cart }) => { + * console.log(cart) + * }) + */ updateLineItem: async ( cartId: string, lineItemId: string, @@ -189,7 +651,7 @@ export class Store { query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ cart: HttpTypes.StoreCart }>( + return this.client.fetch( `/store/carts/${cartId}/line-items/${lineItemId}`, { method: "POST", @@ -199,6 +661,26 @@ export class Store { } ) }, + /** + * This method deletes a line item from a cart. It sends a request to the + * [Remove Line Item](https://docs.medusajs.com/v2/api/store#carts_deletecartsidlineitemsline_id) API route. + * + * Related guide: [How to manage a cart's line items in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/cart/manage-items). + * + * @param cartId - The cart's ID. + * @param lineItemId - The item's ID. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.store.cart.deleteLineItem( + * "cart_123", + * "li_123" + * ) + * .then(({ deleted, parent: cart }) => { + * console.log(deleted, cart) + * }) + */ deleteLineItem: async ( cartId: string, lineItemId: string, @@ -212,13 +694,36 @@ export class Store { } ) }, + /** + * This method adds a shipping method to a cart. It sends a request to + * the [Add Shipping Method](https://docs.medusajs.com/v2/api/store#carts_postcartsidshippingmethods) API routes. + * + * Related guide: [Implement shipping step during checkout](https://docs.medusajs.com/v2/resources/storefront-development/checkout/shipping). + * + * @param cartId - The cart's ID. + * @param body - The shipping method's details. + * @param query - Configure the fields to retrieve in the cart. + * @param headers - Headers to pass in the request. + * @returns The cart's details. + * + * @example + * sdk.store.cart.addShippingMethod("cart_123", { + * option_id: "so_123", + * data: { + * // custom data for fulfillment provider. + * } + * }) + * .then(({ cart }) => { + * console.log(cart) + * }) + */ addShippingMethod: async ( cartId: string, body: HttpTypes.StoreAddCartShippingMethods, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ cart: HttpTypes.StoreCart }>( + return this.client.fetch( `/store/carts/${cartId}/shipping-methods`, { method: "POST", @@ -228,22 +733,37 @@ export class Store { } ) }, + /** + * This method completes a cart and places the order. It's the last step of the checkout flow. + * The method sends a request to the [Complete Cart](https://docs.medusajs.com/v2/api/store#carts_postcartsidcomplete) + * API route. + * + * Related guide: [Learn how to complete cart in checkout flow](https://docs.medusajs.com/v2/resources/storefront-development/checkout/complete-cart). + * + * @param cartId - The cart's ID. + * @param query - Configure the fields to retrieve in the created order. + * @param headers - Headers to pass in the request. + * @returns The order's details, if it was placed successfully. Otherwise, the cart is returned with an error. + * + * @example + * sdk.store.cart.complete("cart_123") + * .then((data) => { + * if(data.type === "cart") { + * // an error occurred + * console.log(data.error, data.cart) + * } else { + * // order placed successfully + * console.log(data.order) + * } + * }) + */ complete: async ( cartId: string, query?: SelectParams, headers?: ClientHeaders ) => { return this.client.fetch< - | { type: "order"; order: HttpTypes.StoreOrder } - | { - type: "cart" - cart: HttpTypes.StoreCart - error: { - message: string - name: string - type: string - } - } + HttpTypes.StoreCompleteCartResponse >(`/store/carts/${cartId}/complete`, { method: "POST", headers, @@ -253,13 +773,32 @@ export class Store { } public fulfillment = { + /** + * This method retrieves the list of shipping options for a cart. It sends a request to + * the [List Shipping Options](https://docs.medusajs.com/v2/api/store#shipping-options_getshippingoptions) + * API route. + * + * Related guide: [Implement shipping step during checkout](https://docs.medusajs.com/v2/resources/storefront-development/checkout/shipping). + * + * @param query - The cart's details along with configurations of the fields to retrieve in the options. + * @param headers - Headers to pass in the request. + * @returns The shipping options that can be used for the cart. + * + * @example + * sdk.store.fulfillment.listCartOptions({ + * cart_id: "cart_123" + * }) + * .then(({ shipping_options }) => { + * console.log(shipping_options) + * }) + */ listCartOptions: async ( - query?: FindParams & { cart_id: string }, + query?: HttpTypes.StoreGetShippingOptionList, headers?: ClientHeaders ) => { - return this.client.fetch<{ - shipping_options: HttpTypes.StoreCartShippingOption[] - }>(`/store/shipping-options`, { + return this.client.fetch< + HttpTypes.StoreShippingOptionListResponse + >(`/store/shipping-options`, { headers, query, }) @@ -267,21 +806,108 @@ export class Store { } public payment = { + /** + * This method retrieves the payment providers available in a region, which is useful during checkout. + * It sends a request to the [List Payment Providers](https://docs.medusajs.com/v2/api/store#payment-providers_getpaymentproviders) + * API route. + * + * Related guide: [Implement payment step during checkout](https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment). + * + * @param query - The filters to apply on the retrieved providers, along with configurations of the + * fields to retrieve in the options. + * @param headers - Headers to pass in the request. + * @returns The list of payment providers. + * + * @example + * To retrieve the list of payment providers for a region: + * + * ```ts + * sdk.store.payment.listPaymentProviders({ + * region_id: "reg_123" + * }) + * .then(({ payment_providers, count, offset, limit }) => { + * console.log(payment_providers) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.payment.listPaymentProviders({ + * region_id: "reg_123", + * limit: 10, + * offset: 10 + * }) + * .then(({ payment_providers, count, offset, limit }) => { + * console.log(payment_providers) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each provider: + * + * ```ts + * sdk.store.payment.listPaymentProviders({ + * region_id: "reg_123", + * limit: 10, + * offset: 10, + * fields: "id" + * }) + * .then(({ payment_providers, count, offset, limit }) => { + * console.log(payment_providers) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ listPaymentProviders: async ( query?: FindParams & HttpTypes.StorePaymentProviderFilters, headers?: ClientHeaders ) => { - return this.client.fetch<{ - payment_providers: HttpTypes.StorePaymentProvider[] - }>(`/store/payment-providers`, { + return this.client.fetch< + HttpTypes.StorePaymentProviderListResponse + >(`/store/payment-providers`, { headers, query, }) }, + /** + * This method creates a payment session of a cart's payment collection, selecting a payment provider. + * It sends a request to the [Initialize Payment Session](https://docs.medusajs.com/v2/api/store#payment-collections_postpaymentcollectionsidpaymentsessions) + * API route. + * + * If the cart doesn't have a payment collection, a payment collection is created for the cart by + * sending a request to the [Create Payment Collection](https://docs.medusajs.com/v2/api/store#payment-collections_postpaymentcollections) + * API route. + * + * Related guide: [Implement payment step during checkout](https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment). + * + * @param cart - The cart's details. + * @param body - The payment session's details. + * @param query - Configure the fields to retrieve in the payment collection. + * @param headers - Headers to pass in the request. + * @returns The payment collection's details. + * + * @example + * sdk.store.payment.initiatePaymentSession( + * cart, // assuming you already have the cart object. + * { + * provider_id: "pp_stripe_stripe", + * data: { + * // any data relevant for the provider. + * } + * } + * ) + * .then(({ payment_collection }) => { + * console.log(payment_collection) + * }) + */ initiatePaymentSession: async ( cart: HttpTypes.StoreCart, - body: Record, + body: HttpTypes.StoreInitializePaymentSession, query?: SelectParams, headers?: ClientHeaders ) => { @@ -291,9 +917,9 @@ export class Store { cart_id: cart.id, } paymentCollectionId = ( - await this.client.fetch<{ - payment_collection: HttpTypes.StorePaymentCollection - }>(`/store/payment-collections`, { + await this.client.fetch< + HttpTypes.StorePaymentCollectionResponse + >(`/store/payment-collections`, { method: "POST", headers, body: collectionBody, @@ -301,9 +927,9 @@ export class Store { ).payment_collection.id } - return this.client.fetch<{ - payment_collection: HttpTypes.StorePaymentCollection - }>(`/store/payment-collections/${paymentCollectionId}/payment-sessions`, { + return this.client.fetch< + HttpTypes.StorePaymentCollectionResponse + >(`/store/payment-collections/${paymentCollectionId}/payment-sessions`, { method: "POST", headers, body, @@ -313,17 +939,96 @@ export class Store { } public order = { + /** + * This method retrieves a paginated list of orders matching the specified filters. It + * sends a request to the [List Orders](https://docs.medusajs.com/v2/api/store#orders_getorders) + * API route. + * + * @param query - Configure the fields to retrieve in the orders. + * @param headers - Headers to pass in the request. + * @returns The paginated list of orders. + * + * @example + * To retrieve the list of orders: + * + * ```ts + * sdk.store.order.list() + * .then(({ orders, count, offset, limit }) => { + * console.log(orders) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.order.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ orders, count, offset, limit }) => { + * console.log(orders) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each order: + * + * ```ts + * sdk.store.order.list({ + * fields: "id,*items" + * }) + * .then(({ orders, count, offset, limit }) => { + * console.log(orders) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ list: async ( - query?: FindParams & HttpTypes.StoreOrderFilters, + query?: HttpTypes.StoreOrderFilters, headers?: ClientHeaders ) => { return this.client.fetch< - PaginatedResponse<{ orders: HttpTypes.StoreOrder[] }> + HttpTypes.StoreOrderListResponse >(`/store/orders`, { query, headers, }) }, + /** + * This method retrieves an order by its ID. It sends a request to the + * [Get Order](https://docs.medusajs.com/v2/api/store#orders_getordersid) API route. + * + * @param id - The order's ID. + * @param query - Configure the fields to retrieve in the order. + * @param headers - Headers to pass in the request. + * @returns The order's details. + * + * @example + * To retrieve an order by its ID: + * + * ```ts + * sdk.store.order.retrieve("order_123") + * .then(({ order }) => { + * console.log(order) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.order.retrieve("order_123", { + * fields: "id,*items" + * }) + * .then(({ order }) => { + * console.log(order) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieve: async ( id: string, query?: SelectParams, @@ -340,26 +1045,83 @@ export class Store { } public customer = { + /** + * This method registers a customer. It sends a request to the [Register Customer](https://docs.medusajs.com/v2/api/store#customers_postcustomers) + * API route. + * + * You must use the {@link Auth.register} method first to retrieve a registration token. Then, pass that + * registration token in the `headers` parameter of this method as an authorization bearer header. + * + * Related guide: [How to register customer in storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/register) + * + * @param body - The customer's details. + * @param query - Configure the fields to retrieve in the customer. + * @param headers - Headers to pass in the request. This is where you include the authorization JWT registration token. + * @returns The customer's details. + * + * @example + * const token = await sdk.auth.register("customer", "emailpass", { + * "email": "customer@gmail.com", + * "password": "supersecret" + * }) + * + * sdk.store.customer.create( + * { + * "email": "customer@gmail.com" + * }, + * {}, + * { + * authorization: `Bearer ${token}` + * } + * ) + * .then(({ customer }) => { + * console.log(customer) + * }) + */ create: async ( body: HttpTypes.StoreCreateCustomer, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ - customer: HttpTypes.StoreCustomer - }>(`/store/customers`, { + return this.client.fetch< + HttpTypes.StoreCustomerResponse + >(`/store/customers`, { method: "POST", headers, body, query, }) }, + /** + * This method updates the logged-in customer's details. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the + * [Update Customer](https://docs.medusajs.com/v2/api/store#customers_postcustomersme) API route. + * + * Related guide: [How to edit customer's profile in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/profile). + * + * @param body - The customer's details to update. + * @param query - Configure the fields to retrieve in the customer. + * @param headers - Headers to pass in the request. + * @returns The customer's details. + * + * @example + * sdk.store.customer.update({ + * first_name: "John" + * }) + * .then(({ customer }) => { + * console.log(customer) + * }) + */ update: async ( body: HttpTypes.StoreUpdateCustomer, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ customer: HttpTypes.StoreCustomer }>( + return this.client.fetch< + HttpTypes.StoreCustomerResponse + >( `/store/customers/me`, { method: "POST", @@ -369,8 +1131,25 @@ export class Store { } ) }, + /** + * This method retrieves the logged-in customer's details. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the [Get Logged-In Customer](https://docs.medusajs.com/v2/api/store#customers_getcustomersme) + * API route. + * + * @param query - Configure the fields to retrieve in the customer. + * @param headers - Headers to pass in the request. + * @returns The customer's details. + * + * @example + * sdk.store.customer.retrieve() + * .then(({ customer }) => { + * console.log(customer) + * }) + */ retrieve: async (query?: SelectParams, headers?: ClientHeaders) => { - return this.client.fetch<{ customer: HttpTypes.StoreCustomer }>( + return this.client.fetch( `/store/customers/me`, { query, @@ -378,27 +1157,77 @@ export class Store { } ) }, + /** + * This method creates an address for the logged-in customer. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the [Create Address](https://docs.medusajs.com/v2/api/store#customers_postcustomersmeaddresses) + * API route. + * + * Related guides: [How to manage customer's addresses in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/addresses) + * + * @param body - The address's details. + * @param query - Configure the fields to retrieve in the customer. + * @param headers - Headers to pass in the request. + * @returns The customer's details. + * + * @example + * sdk.store.customer.createAddress({ + * country_code: "us" + * }) + * .then(({ customer }) => { + * console.log(customer) + * }) + */ createAddress: async ( body: HttpTypes.StoreCreateCustomerAddress, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ - customer: HttpTypes.StoreCustomer - }>(`/store/customers/me/addresses`, { + return this.client.fetch< + HttpTypes.StoreCustomerResponse + >(`/store/customers/me/addresses`, { method: "POST", headers, body, query, }) }, + /** + * This method updates the address of the logged-in customer. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the [Update Address](https://docs.medusajs.com/v2/api/store#customers_postcustomersmeaddressesaddress_id) + * API route. + * + * Related guides: [How to manage customer's addresses in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/addresses) + * + * @param addressId - The ID of the address to update. + * @param body - The details to update in the address. + * @param query - Configure the fields to retrieve in the customer. + * @param headers - Headers to pass in the request. + * @returns The customer's details. + * + * @example + * sdk.store.customer.updateAddress( + * "caddr_123", + * { + * country_code: "us" + * } + * ) + * .then(({ customer }) => { + * console.log(customer) + * }) + */ updateAddress: async ( addressId: string, body: HttpTypes.StoreUpdateCustomerAddress, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ customer: HttpTypes.StoreCustomer }>( + return this.client.fetch< + HttpTypes.StoreCustomerResponse + >( `/store/customers/me/addresses/${addressId}`, { method: "POST", @@ -408,23 +1237,118 @@ export class Store { } ) }, + /** + * This method retrieves the logged-in customer's address. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the [List Customer's Address](https://docs.medusajs.com/v2/api/store#customers_getcustomersmeaddresses) + * API route. + * + * Related guides: [How to manage customer's addresses in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/addresses) + * + * @param query - Configure the fields to retrieve in the addresses. + * @param headers - Headers to pass in the request. + * @returns The paginated list of addresses. + * + * @example + * To retrieve the list of addresses: + * + * ```ts + * sdk.store.customer.listAddress() + * .then(({ addresses, count, offset, limit }) => { + * console.log(addresses) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.store.customer.listAddress({ + * limit: 10, + * offset: 10 + * }) + * .then(({ addresses, count, offset, limit }) => { + * console.log(addresses) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each address: + * + * ```ts + * sdk.store.customer.listAddress({ + * fields: "id,country_code" + * }) + * .then(({ addresses, count, offset, limit }) => { + * console.log(addresses) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ listAddress: async ( query?: FindParams & HttpTypes.StoreCustomerAddressFilters, headers?: ClientHeaders ) => { return this.client.fetch< - PaginatedResponse<{ addresses: HttpTypes.StoreCustomerAddress[] }> + HttpTypes.StoreCustomerAddressListResponse >(`/store/customers/me/addresses`, { query, headers, }) }, + /** + * This method retrieves an address of the logged-in customer. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the [Get Address](https://docs.medusajs.com/v2/api/store#customers_getcustomersmeaddressesaddress_id) + * API route. + * + * Related guides: [How to manage customer's addresses in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/addresses) + * + * @param addressId - The address's ID. + * @param query - Configure the fields to retrieve in the address. + * @param headers - Headers to pass in the request. + * @returns The address's details. + * + * @example + * To retrieve an address by its ID: + * + * ```ts + * sdk.store.customer.retrieveAddress( + * "caddr_123" + * ) + * .then(({ address }) => { + * console.log(address) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.store.customer.retrieveAddress( + * "caddr_123", + * { + * fields: "id,country_code" + * } + * ) + * .then(({ address }) => { + * console.log(address) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ retrieveAddress: async ( addressId: string, query?: SelectParams, headers?: ClientHeaders ) => { - return this.client.fetch<{ address: HttpTypes.StoreCustomerAddress }>( + return this.client.fetch< + HttpTypes.StoreCustomerAddressResponse + >( `/store/customers/me/addresses/${addressId}`, { query, @@ -432,6 +1356,25 @@ export class Store { } ) }, + /** + * This method deletes an address of the logged-in customer. The customer must be logged in + * first with the {@link Auth.login} method. + * + * It sends a request to the [Remove Address](https://docs.medusajs.com/v2/api/store#customers_deletecustomersmeaddressesaddress_id) + * API route. + * + * Related guides: [How to manage customer's addresses in the storefront](https://docs.medusajs.com/v2/resources/storefront-development/customers/addresses) + * + * @param addressId - The address's ID. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.store.customer.deleteAddress("caddr_123") + * .then(({ deleted, parent: customer }) => { + * console.log(customer) + * }) + */ deleteAddress: async (addressId: string, headers?: ClientHeaders) => { return this.client.fetch( `/store/customers/me/addresses/${addressId}`, diff --git a/packages/core/js-sdk/src/types.ts b/packages/core/js-sdk/src/types.ts index b2ada0255e357..866c80b7453c5 100644 --- a/packages/core/js-sdk/src/types.ts +++ b/packages/core/js-sdk/src/types.ts @@ -22,8 +22,14 @@ export type Config = { export type FetchParams = Parameters export type ClientHeaders = - // The `tags` header is specifically added for nextJS, as they follow a non-standard header format - Record + Record export type FetchInput = FetchParams[0] diff --git a/packages/core/types/src/http/cart/store/entities.ts b/packages/core/types/src/http/cart/store/entities.ts index 64e7916acc80e..88ae82b41e28b 100644 --- a/packages/core/types/src/http/cart/store/entities.ts +++ b/packages/core/types/src/http/cart/store/entities.ts @@ -13,30 +13,69 @@ import { } from "../common" export interface StoreCart extends Omit { + /** + * 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 { + /** + * 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 })[] diff --git a/packages/core/types/src/http/cart/store/payloads.ts b/packages/core/types/src/http/cart/store/payloads.ts index 2cf1262b1414f..bbf8807c3e2eb 100644 --- a/packages/core/types/src/http/cart/store/payloads.ts +++ b/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 } 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 + /** + * 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 } export interface StoreUpdateCartLineItem { + /** + * The item's quantity. + */ quantity: number + /** + * Key-value pairs of custom data. + */ metadata?: Record } 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 } diff --git a/packages/core/types/src/http/cart/store/responses.ts b/packages/core/types/src/http/cart/store/responses.ts index 57e91260e1c14..d21b1ac897bbb 100644 --- a/packages/core/types/src/http/cart/store/responses.ts +++ b/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 } diff --git a/packages/core/types/src/http/collection/common.ts b/packages/core/types/src/http/collection/common.ts index 3bc6e82ce38eb..bdd5acab23cb4 100644 --- a/packages/core/types/src/http/collection/common.ts +++ b/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 | null } @@ -18,10 +42,28 @@ export interface BaseCollectionParams extends SelectParams {} export interface BaseCollectionListParams extends FindParams, BaseFilterable { + /** + * 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 + /** + * Apply filters on collection update dates. + */ updated_at?: OperatorMap } diff --git a/packages/core/types/src/http/collection/store/entities.ts b/packages/core/types/src/http/collection/store/entities.ts index bf2062ef1be68..ded1f4243fd63 100644 --- a/packages/core/types/src/http/collection/store/entities.ts +++ b/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 { + /** + * The collection's products. + */ products?: StoreProduct[] } diff --git a/packages/core/types/src/http/collection/store/queries.ts b/packages/core/types/src/http/collection/store/queries.ts index 44e633a9c7d2b..0dfa10a564720 100644 --- a/packages/core/types/src/http/collection/store/queries.ts +++ b/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 { - deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/collection/store/responses.ts b/packages/core/types/src/http/collection/store/responses.ts index 89da32b08bf2b..8b956b49bb35e 100644 --- a/packages/core/types/src/http/collection/store/responses.ts +++ b/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[] }> diff --git a/packages/core/types/src/http/common/request.ts b/packages/core/types/src/http/common/request.ts index b9ce27f1bd596..786d5da45d15a 100644 --- a/packages/core/types/src/http/common/request.ts +++ b/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 } diff --git a/packages/core/types/src/http/common/response.ts b/packages/core/types/src/http/common/response.ts index cbbc0972abc72..29f679d52777e 100644 --- a/packages/core/types/src/http/common/response.ts +++ b/packages/core/types/src/http/common/response.ts @@ -26,8 +26,17 @@ export type DeleteResponseWithParent< } export type PaginatedResponse = { + /** + * 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 diff --git a/packages/core/types/src/http/customer/common.ts b/packages/core/types/src/http/customer/common.ts index e0a1728e04d28..9264b9ea8ccd0 100644 --- a/packages/core/types/src/http/customer/common.ts +++ b/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 | 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 + /** + * 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 { + /** + * 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 } 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 } 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 + /** + * 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 | 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 } diff --git a/packages/core/types/src/http/customer/store/entities.ts b/packages/core/types/src/http/customer/store/entities.ts index aeb274566dd68..8bae9e22cf5b3 100644 --- a/packages/core/types/src/http/customer/store/entities.ts +++ b/packages/core/types/src/http/customer/store/entities.ts @@ -1,6 +1,9 @@ import { BaseCustomer, BaseCustomerAddress } from "../common" export interface StoreCustomer extends Omit { + /** + * The customer's address. + */ addresses: StoreCustomerAddress[] } export interface StoreCustomerAddress extends BaseCustomerAddress {} diff --git a/packages/core/types/src/http/customer/store/responses.ts b/packages/core/types/src/http/customer/store/responses.ts index 92ff8eb26633f..7ada39e2e5331 100644 --- a/packages/core/types/src/http/customer/store/responses.ts +++ b/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", diff --git a/packages/core/types/src/http/fulfillment/store/index.ts b/packages/core/types/src/http/fulfillment/store/index.ts index dd787d11a4f95..25fe22d6984f5 100644 --- a/packages/core/types/src/http/fulfillment/store/index.ts +++ b/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 | 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 } diff --git a/packages/core/types/src/http/order/common.ts b/packages/core/types/src/http/order/common.ts index a3b6cb9a48079..07f6730e22f10 100644 --- a/packages/core/types/src/http/order/common.ts +++ b/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 | 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 | null + /** + * Key-value pairs of custom data. + */ metadata: Record | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 } diff --git a/packages/core/types/src/http/order/store/entities.ts b/packages/core/types/src/http/order/store/entities.ts index f82aca5e3ae86..905fec4c7e9f2 100644 --- a/packages/core/types/src/http/order/store/entities.ts +++ b/packages/core/types/src/http/order/store/entities.ts @@ -18,29 +18,68 @@ import { export interface StoreOrder extends Omit { + /** + * 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 { + /** + * 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 { diff --git a/packages/core/types/src/http/order/store/queries.ts b/packages/core/types/src/http/order/store/queries.ts index a48b1e29b7f44..e4b64b489f6e4 100644 --- a/packages/core/types/src/http/order/store/queries.ts +++ b/packages/core/types/src/http/order/store/queries.ts @@ -5,6 +5,12 @@ import { FindParams } from "../../common" export interface StoreOrderFilters extends FindParams, BaseFilterable { + /** + * Filter by order ID(s). + */ id?: string | string[] + /** + * Filter by order status(es). + */ status?: OrderStatus | OrderStatus[] } diff --git a/packages/core/types/src/http/order/store/responses.ts b/packages/core/types/src/http/order/store/responses.ts index 0aec6f75361c4..1495e91c8347b 100644 --- a/packages/core/types/src/http/order/store/responses.ts +++ b/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[] +}> diff --git a/packages/core/types/src/http/payment/common.ts b/packages/core/types/src/http/payment/common.ts index e975cb4c63524..35a40726d1327 100644 --- a/packages/core/types/src/http/payment/common.ts +++ b/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 } diff --git a/packages/core/types/src/http/payment/store/entities.ts b/packages/core/types/src/http/payment/store/entities.ts index 5bb6f453b7cd1..d7199a4770efc 100644 --- a/packages/core/types/src/http/payment/store/entities.ts +++ b/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 } diff --git a/packages/core/types/src/http/payment/store/payloads.ts b/packages/core/types/src/http/payment/store/payloads.ts index 82ccc9b2f9de8..22be0a061f80d 100644 --- a/packages/core/types/src/http/payment/store/payloads.ts +++ b/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 + /** + * 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 +} \ No newline at end of file diff --git a/packages/core/types/src/http/payment/store/queries.ts b/packages/core/types/src/http/payment/store/queries.ts index b657bba9c9edb..4be032e09e0c1 100644 --- a/packages/core/types/src/http/payment/store/queries.ts +++ b/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 diff --git a/packages/core/types/src/http/payment/store/responses.ts b/packages/core/types/src/http/payment/store/responses.ts index bd59df3197edb..ea76b8dc1f304 100644 --- a/packages/core/types/src/http/payment/store/responses.ts +++ b/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[] }> diff --git a/packages/core/types/src/http/product-category/common.ts b/packages/core/types/src/http/product-category/common.ts index 667492309c787..2f689a9f1f856 100644 --- a/packages/core/types/src/http/product-category/common.ts +++ b/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 | 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 { + /** + * 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 + /** + * Apply filters on the category's update date. + */ updated_at?: OperatorMap + /** + * Apply filters on the category's deletion date. + */ deleted_at?: OperatorMap } 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 } diff --git a/packages/core/types/src/http/product-category/store/entities.ts b/packages/core/types/src/http/product-category/store/entities.ts index 2d0f254d12b5f..a90a8adfdbe6f 100644 --- a/packages/core/types/src/http/product-category/store/entities.ts +++ b/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[] } diff --git a/packages/core/types/src/http/product-category/store/queries.ts b/packages/core/types/src/http/product-category/store/queries.ts index 73e531e43779e..5539396adcd33 100644 --- a/packages/core/types/src/http/product-category/store/queries.ts +++ b/packages/core/types/src/http/product-category/store/queries.ts @@ -4,6 +4,6 @@ import { } from "../common" export interface StoreProductCategoryListParams - extends Omit {} + extends Omit {} export interface StoreProductCategoryParams extends BaseProductCategoryParams {} diff --git a/packages/core/types/src/http/product-category/store/responses.ts b/packages/core/types/src/http/product-category/store/responses.ts index 44fdcfcab48d3..705add8f0f713 100644 --- a/packages/core/types/src/http/product-category/store/responses.ts +++ b/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[] }> {} diff --git a/packages/core/types/src/http/product/common.ts b/packages/core/types/src/http/product/common.ts index e6f209841d90b..9b3a0cde117e3 100644 --- a/packages/core/types/src/http/product/common.ts +++ b/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 | 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 | 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 | 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 | 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 { + /** + * 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 + /** + * Apply filers on the product's update date. + */ updated_at?: OperatorMap + /** + * Apply filers on the product's deletion date. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/product/store/entitites.ts b/packages/core/types/src/http/product/store/entitites.ts index e621616160580..ac4a3b733a10f 100644 --- a/packages/core/types/src/http/product/store/entitites.ts +++ b/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 { + /** + * The variant's values for the product's options. + */ options: StoreProductOptionValue[] | null + /** + * The variant's product. + */ product?: StoreProduct | null } export interface StoreProductOption extends Omit { + /** + * 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 { + /** + * The product's option. + */ option?: StoreProductOption | null } export type StoreProductStatus = ProductStatus diff --git a/packages/core/types/src/http/product/store/queries.ts b/packages/core/types/src/http/product/store/queries.ts index 90f7ea2a1f7d9..e7b71fbedd413 100644 --- a/packages/core/types/src/http/product/store/queries.ts +++ b/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 { + extends Omit { + /** + * 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 + /** + * 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 } diff --git a/packages/core/types/src/http/product/store/responses.ts b/packages/core/types/src/http/product/store/responses.ts index 929661860d46c..0b10deea9ed2d 100644 --- a/packages/core/types/src/http/product/store/responses.ts +++ b/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[] }> diff --git a/packages/core/types/src/http/region/common.ts b/packages/core/types/src/http/region/common.ts index 9517a931e2ccf..5a209782d890e 100644 --- a/packages/core/types/src/http/region/common.ts +++ b/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 | 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 { + /** + * A query or keywords to search a region's searchable fields by. + */ q?: string + /** + * Filter by region ID(s). + */ id?: string[] | string | OperatorMap + /** + * 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 + /** + * Apply filters on the region's update date. + */ updated_at?: OperatorMap } diff --git a/packages/core/types/src/http/region/store/responses.ts b/packages/core/types/src/http/region/store/responses.ts index 955ea62940dcf..b73616e047801 100644 --- a/packages/core/types/src/http/region/store/responses.ts +++ b/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[] }> diff --git a/packages/core/types/src/http/shipping-option/store/queries.ts b/packages/core/types/src/http/shipping-option/store/queries.ts index e1a55ba6c0f70..4c92554e80872 100644 --- a/packages/core/types/src/http/shipping-option/store/queries.ts +++ b/packages/core/types/src/http/shipping-option/store/queries.ts @@ -4,5 +4,13 @@ import { FindParams } from "../../common" export interface StoreGetShippingOptionList extends FindParams, BaseFilterable { + /** + * 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 } diff --git a/packages/core/types/src/http/shipping-option/store/responses.ts b/packages/core/types/src/http/shipping-option/store/responses.ts index 2c5f44609973b..bb7df6ad0bea4 100644 --- a/packages/core/types/src/http/shipping-option/store/responses.ts +++ b/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[] } diff --git a/packages/medusa/src/api/store/collections/validators.ts b/packages/medusa/src/api/store/collections/validators.ts index d8b34bc887b41..c8a1ae9e9b2f9 100644 --- a/packages/medusa/src/api/store/collections/validators.ts +++ b/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(), }) diff --git a/packages/medusa/src/api/store/payment-collections/[id]/payment-sessions/route.ts b/packages/medusa/src/api/store/payment-collections/[id]/payment-sessions/route.ts index a01707893e7a5..b03364c8dbb00 100644 --- a/packages/medusa/src/api/store/payment-collections/[id]/payment-sessions/route.ts +++ b/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, + req: AuthenticatedMedusaRequest, res: MedusaResponse ) => { const collectionId = req.params.id