From 768ea91e1bfa2a2c1376365ea46de265046b4e91 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 25 Mar 2025 14:55:54 +0200 Subject: [PATCH] chore(js-sdk,types): add missing examples for JS SDK methods (#11934) * chore(js-sdk,types): add TSDocs for calculate method * added tsdocs for promotions * finished adding examples * fixes * remove unused import --- packages/core/js-sdk/src/admin/campaign.ts | 9 + .../js-sdk/src/admin/fulfillment-provider.ts | 8 +- packages/core/js-sdk/src/admin/promotion.ts | 284 ++++++++++ .../core/js-sdk/src/admin/refund-reasons.ts | 48 ++ packages/core/js-sdk/src/admin/region.ts | 153 ++++- packages/core/js-sdk/src/admin/reservation.ts | 134 +++++ .../core/js-sdk/src/admin/return-reason.ts | 135 +++++ packages/core/js-sdk/src/admin/return.ts | 522 ++++++++++++++++++ .../core/js-sdk/src/admin/sales-channel.ts | 173 ++++++ .../core/js-sdk/src/admin/shipping-option.ts | 152 ++++- .../core/js-sdk/src/admin/shipping-profile.ts | 132 +++++ .../core/js-sdk/src/admin/stock-location.ts | 190 +++++++ packages/core/js-sdk/src/admin/store.ts | 99 ++++ packages/core/js-sdk/src/admin/tax-rate.ts | 136 +++++ packages/core/js-sdk/src/admin/tax-region.ts | 126 ++++- packages/core/js-sdk/src/admin/upload.ts | 68 ++- packages/core/js-sdk/src/admin/user.ts | 147 +++++ .../js-sdk/src/admin/workflow-execution.ts | 62 +++ packages/core/js-sdk/src/store/index.ts | 19 + .../core/types/src/http/common/request.ts | 4 +- .../core/types/src/http/common/response.ts | 21 + .../types/src/http/file/admin/responses.ts | 6 + packages/core/types/src/http/file/common.ts | 22 +- .../fulfillment-provider/admin/responses.ts | 3 + .../types/src/http/payment/admin/queries.ts | 6 + .../types/src/http/payment/admin/responses.ts | 3 + .../src/http/promotion/admin/entities.ts | 20 + .../src/http/promotion/admin/payloads.ts | 156 ++++++ .../types/src/http/promotion/admin/queries.ts | 44 ++ .../src/http/promotion/admin/responses.ts | 15 + .../core/types/src/http/promotion/common.ts | 53 ++ .../types/src/http/region/admin/entities.ts | 3 + .../types/src/http/region/admin/payloads.ts | 68 +++ .../types/src/http/region/admin/queries.ts | 21 + .../types/src/http/region/admin/responses.ts | 6 + .../src/http/reservation/admin/entities.ts | 39 ++ .../src/http/reservation/admin/payloads.ts | 32 ++ .../src/http/reservation/admin/queries.ts | 34 ++ .../src/http/reservation/admin/responses.ts | 6 + .../src/http/return-reason/admin/payloads.ts | 21 + .../src/http/return-reason/admin/queries.ts | 3 + .../src/http/return-reason/admin/responses.ts | 6 + .../types/src/http/return-reason/common.ts | 27 + .../types/src/http/return/admin/entities.ts | 3 + .../types/src/http/return/admin/payloads.ts | 166 +++++- .../types/src/http/return/admin/queries.ts | 15 + .../types/src/http/return/admin/responses.ts | 6 + packages/core/types/src/http/return/common.ts | 73 +++ .../src/http/sales-channel/admin/entities.ts | 24 + .../src/http/sales-channel/admin/payloads.ts | 32 ++ .../src/http/sales-channel/admin/queries.ts | 32 ++ .../src/http/sales-channel/admin/responses.ts | 6 + .../http/shipping-option/admin/entities.ts | 188 ++++++- .../http/shipping-option/admin/payloads.ts | 181 ++++++ .../src/http/shipping-option/admin/queries.ts | 36 ++ .../http/shipping-option/admin/responses.ts | 6 + .../http/shipping-option/store/payloads.ts | 12 + .../http/shipping-option/store/responses.ts | 12 + .../http/shipping-profile/admin/entities.ts | 21 + .../http/shipping-profile/admin/payloads.ts | 18 + .../http/shipping-profile/admin/queries.ts | 27 + .../http/shipping-profile/admin/responses.ts | 6 + .../http/stock-locations/admin/entities.ts | 21 + .../http/stock-locations/admin/payloads.ts | 69 +++ .../src/http/stock-locations/admin/queries.ts | 26 +- .../http/stock-locations/admin/responses.ts | 6 + .../types/src/http/store/admin/entities.ts | 54 ++ .../types/src/http/store/admin/queries.ts | 9 + .../types/src/http/store/admin/responses.ts | 6 + .../types/src/http/tax-rate/admin/entities.ts | 54 ++ .../types/src/http/tax-rate/admin/payloads.ts | 57 ++ .../types/src/http/tax-rate/admin/queries.ts | 30 + .../src/http/tax-rate/admin/responses.ts | 6 + .../src/http/tax-region/admin/entities.ts | 42 ++ .../src/http/tax-region/admin/payloads.ts | 30 + .../src/http/tax-region/admin/queries.ts | 28 + .../src/http/tax-region/admin/responses.ts | 6 + .../types/src/http/user/admin/entities.ts | 27 + .../types/src/http/user/admin/payloads.ts | 12 + .../core/types/src/http/user/admin/queries.ts | 24 + .../types/src/http/user/admin/responses.ts | 10 +- .../http/workflow-execution/admin/entities.ts | 135 +++++ .../http/workflow-execution/admin/queries.ts | 6 + .../workflow-execution/admin/responses.ts | 6 + 84 files changed, 4719 insertions(+), 25 deletions(-) diff --git a/packages/core/js-sdk/src/admin/campaign.ts b/packages/core/js-sdk/src/admin/campaign.ts index 3bb344f1cd..5150c1d384 100644 --- a/packages/core/js-sdk/src/admin/campaign.ts +++ b/packages/core/js-sdk/src/admin/campaign.ts @@ -214,6 +214,15 @@ export class Campaign { * @param payload - The promotions to add or remove associations to them. * @param headers - Headers to pass in the request * @returns The campaign's details. + * + * @example + * sdk.admin.campaign.batchPromotions("procamp_123", { + * add: ["prom_123", "prom_456"], + * remove: ["prom_789"] + * }) + * .then(({ campaign }) => { + * console.log(campaign) + * }) */ async batchPromotions( id: string, diff --git a/packages/core/js-sdk/src/admin/fulfillment-provider.ts b/packages/core/js-sdk/src/admin/fulfillment-provider.ts index dce206e026..21d04a1582 100644 --- a/packages/core/js-sdk/src/admin/fulfillment-provider.ts +++ b/packages/core/js-sdk/src/admin/fulfillment-provider.ts @@ -77,12 +77,18 @@ export class FulfillmentProvider { /** * This method retrieves a list of fulfillment options for a given fulfillment provider. It sends a request to the - * [List Fulfillment Options](https://docs.medusajs.com/api/admin#fulfillment-providers_getfulfillmentprovideroptions) + * [List Fulfillment Options](https://docs.medusajs.com/api/admin#fulfillment-providers_getfulfillmentprovidersidoptions) * API route. * * @param id - The ID of the fulfillment provider. * @param headers - Headers to pass in the request. * @returns The list of fulfillment options. + * + * @example + * sdk.admin.fulfillmentProvider.listFulfillmentOptions("fp_123") + * .then(({ fulfillment_options }) => { + * console.log(fulfillment_options) + * }) */ async listFulfillmentOptions(id: string, headers?: ClientHeaders) { return await this.client.fetch( diff --git a/packages/core/js-sdk/src/admin/promotion.ts b/packages/core/js-sdk/src/admin/promotion.ts index 924fc93dfe..14db44ab01 100644 --- a/packages/core/js-sdk/src/admin/promotion.ts +++ b/packages/core/js-sdk/src/admin/promotion.ts @@ -14,6 +14,39 @@ export class Promotion { this.client = client } + /** + * This method retrieves a promotion by its ID. It sends a request to the + * [Retrieve Promotion](https://docs.medusajs.com/api/admin#promotions_getpromotionsid) + * API route. + * + * @param id - The promotion's ID. + * @param query - Configure the fields to retrieve in the promotion. + * @param headers - Headers to pass in the request. + * @returns The promotion's details. + * + * @example + * To retrieve a promotion by its ID: + * + * ```ts + * sdk.admin.promotion.retrieve("promo_123") + * .then(({ promotion }) => { + * console.log(promotion) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.promotion.retrieve("promo_123", { + * fields: "id,*application_method" + * }) + * .then(({ promotion }) => { + * console.log(promotion) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.AdminGetPromotionParams, @@ -28,6 +61,53 @@ export class Promotion { ) } + /** + * This method retrieves a list of promotions. It sends a request to the + * [List Promotions](https://docs.medusajs.com/api/admin#promotions_getpromotions) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of promotions. + * + * @example + * To retrieve the list of promotions: + * + * ```ts + * sdk.admin.promotion.list() + * .then(({ promotions, count, limit, offset }) => { + * console.log(promotions) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.promotion.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ promotions, count, limit, offset }) => { + * console.log(promotions) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each promotion: + * + * ```ts + * sdk.admin.promotion.list({ + * fields: "id,*application_method" + * }) + * .then(({ promotions, count, limit, offset }) => { + * console.log(promotions) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminGetPromotionsParams, headers?: ClientHeaders @@ -41,6 +121,27 @@ export class Promotion { ) } + /** + * This method creates a new promotion. It sends a request to the + * [Create Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotions) + * API route. + * + * @param payload - The promotion to create. + * @param headers - Headers to pass in the request. + * @returns The promotion's details. + * + * @example + * sdk.admin.promotion.create({ + * name: "My Promotion", + * description: "This is a test promotion", + * code: "PROMO123", + * starts_at: "2021-01-01", + * ends_at: "2021-01-01", + * }) + * .then(({ promotion }) => { + * console.log(promotion) + * }) + */ async create( payload: HttpTypes.AdminCreatePromotion, headers?: ClientHeaders @@ -55,6 +156,24 @@ export class Promotion { ) } + /** + * This method updates a promotion. It sends a request to the + * [Update Promotion](https://docs.medusajs.com/api/admin#promotions_postpromotionsid) + * API route. + * + * @param id - The promotion's ID. + * @param payload - The details to update in the promotion. + * @param headers - Headers to pass in the request. + * @returns The promotion's details. + * + * @example + * sdk.admin.promotion.update("promo_123", { + * code: "PROMO123", + * }) + * .then(({ promotion }) => { + * console.log(promotion) + * }) + */ async update( id: string, payload: HttpTypes.AdminUpdatePromotion, @@ -70,6 +189,21 @@ export class Promotion { ) } + /** + * This method deletes a promotion. It sends a request to the + * [Delete Promotion](https://docs.medusajs.com/api/admin#promotions_deletepromotionsid) + * API route. + * + * @param id - The promotion's ID. + * @param headers - Headers to pass in the request. + * @returns The deleted promotion's details. + * + * @example + * sdk.admin.promotion.delete("promo_123") + * .then(({ promotion }) => { + * console.log(promotion) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch>( `/admin/promotions/${id}`, @@ -80,6 +214,38 @@ export class Promotion { ) } + /** + * This method creates and adds rules to a promotion. It can be the promotion's rules, + * or its application method's buy or target rules. That depends on the rule type + * you specify as a parameter. + * + * - If you set the `ruleType` to `rules`, the method sends a request to the + * [Manage Promotion's Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidrulesbatch). + * - If you set the `ruleType` to `buy-rules`, the method sends a request to the + * [Manage Promotion's Buy Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidbuyrulesbatch). + * - If you set the `ruleType` to `target-rules`, the method sends a request to the + * [Manage Promotion's Target Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidtargetrulesbatch). + * + * @param id - The promotion's ID. + * @param ruleType - The type of rules to create. + * @param payload - The rules to create. + * @param headers - Headers to pass in the request. + * @returns The promotion's details. + * + * @example + * sdk.admin.promotion.addRules("promo_123", "rules", { + * rules: [ + * { + * operator: "eq", + * attribute: "product_id", + * values: ["prod_123"] + * } + * ] + * }) + * .then(({ promotion }) => { + * console.log(promotion) + * }) + */ async addRules( id: string, ruleType: string, @@ -96,6 +262,37 @@ export class Promotion { ) } + /** + * This method updates the rules of a promotion. It can be the promotion's rules, + * or its application method's buy or target rules. That depends on the rule type + * you specify as a parameter. + * + * - If you set the `ruleType` to `rules`, the method sends a request to the + * [Manage Promotion's Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidrulesbatch). + * - If you set the `ruleType` to `buy-rules`, the method sends a request to the + * [Manage Promotion's Buy Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidbuyrulesbatch). + * - If you set the `ruleType` to `target-rules`, the method sends a request to the + * [Manage Promotion's Target Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidtargetrulesbatch). + * + * @param id - The promotion's ID. + * @param ruleType - The type of rules to update. + * @param payload - The rules to update. + * @param headers - Headers to pass in the request. + * @returns The promotion's details. + * + * @example + * sdk.admin.promotion.updateRules("promo_123", "rules", { + * rules: [ + * { + * id: "rule_123", + * operator: "ne", + * } + * ] + * }) + * .then(({ promotion }) => { + * console.log(promotion) + * }) + */ async updateRules( id: string, ruleType: string, @@ -112,6 +309,32 @@ export class Promotion { ) } + /** + * This method removes rules from a promotion. It can be the promotion's rules, + * or its application method's buy or target rules. That depends on the rule type + * you specify as a parameter. + * + * - If you set the `ruleType` to `rules`, the method sends a request to the + * [Manage Promotion's Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidrulesbatch). + * - If you set the `ruleType` to `buy-rules`, the method sends a request to the + * [Manage Promotion's Buy Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidbuyrulesbatch). + * - If you set the `ruleType` to `target-rules`, the method sends a request to the + * [Manage Promotion's Target Rules API Route](https://docs.medusajs.com/api/admin#promotions_postpromotionsidtargetrulesbatch). + * + * @param id - The promotion's ID. + * @param ruleType - The type of rules to remove. + * @param payload - The rules to remove. + * @param headers - Headers to pass in the request. + * @returns The promotion's details. + * + * @example + * sdk.admin.promotion.removeRules("promo_123", "rules", { + * rule_ids: ["rule_123"] + * }) + * .then(({ promotion }) => { + * console.log(promotion) + * }) + */ async removeRules( id: string, ruleType: string, @@ -128,6 +351,26 @@ export class Promotion { ) } + /** + * This method retrieves the rules of a promotion. It can be the promotion's rules, + * or its application method's buy or target rules. That depends on the rule type + * you specify as a parameter. + * + * This method sends a request to the + * [List Rules of a Promotion API Route](https://docs.medusajs.com/api/admin#promotions_getpromotionsidrule_type) + * + * @param id - The promotion's ID. + * @param ruleType - The type of rules to retrieve. Can be `rules`, `buy-rules`, or `target-rules`. + * @param query - Configure the fields to retrieve in the rules. + * @param headers - Headers to pass in the request. + * @returns The promotion's rules. + * + * @example + * sdk.admin.promotion.listRules("promo_123", "rules") + * .then(({ rules }) => { + * console.log(rules) + * }) + */ async listRules( id: string | null, ruleType: string, @@ -144,6 +387,27 @@ export class Promotion { ) } + /** + * Retrieve a list of potential rule attributes for the promotion and application method types specified in the query parameters. Only the attributes of the rule type specified in the path parameter are retrieved: + * + * - If `rule_type` is `rules`, the attributes of the promotion's type are retrieved. + * - If `rule_type` is `target-rules`, the target rules' attributes of the application method's type are retrieved. + * - If `rule_type` is `buy-rules`, the buy rules' attributes of the application method's type are retrieved. + * + * This method sends a request to the + * [List Rule Attribute Options API Route](https://docs.medusajs.com/api/admin#promotions_getpromotionsruleattributeoptionsrule_type) + * + * @param ruleType - The type of rules to retrieve the attributes for. Can be `rules`, `buy-rules`, or `target-rules`. + * @param promotionType - The type of promotion to retrieve the attributes for. It can be `standard` or `buyget`. + * @param headers - Headers to pass in the request. + * @returns The list of rule attributes. + * + * @example + * sdk.admin.promotion.listRuleAttributes("rules", "standard") + * .then(({ attributes }) => { + * console.log(attributes) + * }) + */ async listRuleAttributes( ruleType: string, promotionType?: string, @@ -159,6 +423,26 @@ export class Promotion { ) } + /** + * Retrieve all potential values for promotion rules and target and buy rules based on the specified rule attribute and type. + * For example, if you provide the ID of the `currency_code` rule attribute, and set `rule_type` to rules, + * a list of currencies are retrieved in label-value pairs. + * + * This method sends a request to the + * [List Rule Values API Route](https://docs.medusajs.com/api/admin#promotions_getpromotionsrulevalueoptionsrule_typerule_attribute_id) + * + * @param ruleType - The type of rules to retrieve the values for. Can be `rules`, `buy-rules`, or `target-rules`. + * @param ruleValue - The ID of the rule attribute to retrieve the values for. + * @param query - Configure the fields to retrieve in the rule values. + * @param headers - Headers to pass in the request. + * @returns The list of rule values. + * + * @example + * sdk.admin.promotion.listRuleValues("rules", "attr_123") + * .then(({ values }) => { + * console.log(values) + * }) + */ async listRuleValues( ruleType: string, ruleValue: string, diff --git a/packages/core/js-sdk/src/admin/refund-reasons.ts b/packages/core/js-sdk/src/admin/refund-reasons.ts index 0cd10cd28c..1c6403e270 100644 --- a/packages/core/js-sdk/src/admin/refund-reasons.ts +++ b/packages/core/js-sdk/src/admin/refund-reasons.ts @@ -14,6 +14,54 @@ export class RefundReason { this.client = client } + /** + * This method retrieves a list of refund reasons. It sends a request to the + * [List Refund Reasons](https://docs.medusajs.com/api/admin#refund-reasons_getrefundreasons) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of refund reasons. + * + * @example + * To retrieve the list of refund reasons: + * + * ```ts + * sdk.admin.refundReason.list() + * .then(({ refund_reasons, count, limit, offset }) => { + * console.log(refund_reasons) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.refundReason.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ refund_reasons, count, limit, offset }) => { + * console.log(refund_reasons) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each refund reason: + * + * ```ts + * sdk.admin.refundReason.list({ + * fields: "id,name" + * }) + * .then(({ refund_reasons, count, limit, offset }) => { + * console.log(refund_reasons) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + * + */ async list(query?: HttpTypes.RefundReasonFilters, headers?: ClientHeaders) { return await this.client.fetch( `/admin/refund-reasons`, diff --git a/packages/core/js-sdk/src/admin/region.ts b/packages/core/js-sdk/src/admin/region.ts index 9eeb307bea..5dc1809cef 100644 --- a/packages/core/js-sdk/src/admin/region.ts +++ b/packages/core/js-sdk/src/admin/region.ts @@ -1,7 +1,6 @@ import { FindParams, HttpTypes, - PaginatedResponse, SelectParams, } from "@medusajs/types" import { Client } from "../client" @@ -19,12 +18,31 @@ export class Region { this.client = client } + /** + * This method creates a new region. It sends a request to the + * [Create Region](https://docs.medusajs.com/api/admin#regions_postregions) + * API route. + * + * @param body - The details of the region to create. + * @param query - Configure the fields and relations to retrieve in the region. + * @param headers - Headers to pass in the request. + * @returns The created region's details. + * + * @example + * sdk.admin.region.create({ + * name: "United States", + * currency_code: "usd", + * }) + * .then(({ region }) => { + * console.log(region) + * }) + */ async create( body: HttpTypes.AdminCreateRegion, query?: SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch<{ region: HttpTypes.AdminRegion }>( + return await this.client.fetch( `/admin/regions`, { method: "POST", @@ -35,13 +53,32 @@ export class Region { ) } + /** + * This method updates a region. It sends a request to the + * [Update Region](https://docs.medusajs.com/api/admin#regions_postregionsid) + * API route. + * + * @param id - The ID of the region to update. + * @param body - The details of the region to update. + * @param query - Configure the fields and relations to retrieve in the region. + * @param headers - Headers to pass in the request. + * @returns The updated region's details. + * + * @example + * sdk.admin.region.update("region_123", { + * name: "United States", + * }) + * .then(({ region }) => { + * console.log(region) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateRegion, query?: SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch<{ region: HttpTypes.AdminRegion }>( + return await this.client.fetch( `/admin/regions/${id}`, { method: "POST", @@ -52,20 +89,101 @@ export class Region { ) } + /** + * This method retrieves a list of regions. It sends a request to the + * [List Regions](https://docs.medusajs.com/api/admin#regions_getregions) + * API route. + * + * @param queryParams - 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.admin.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.admin.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.admin.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/api/admin#select-fields-and-relations). + */ async list( queryParams?: FindParams & HttpTypes.AdminRegionFilters, headers?: ClientHeaders ) { - return await this.client.fetch< - PaginatedResponse<{ regions: HttpTypes.AdminRegion[] }> - >(`/admin/regions`, { - query: queryParams, - headers, - }) + return await this.client.fetch( + `/admin/regions`, + { + query: queryParams, + headers, + } + ) } + /** + * This method retrieves a region by ID. It sends a request to the + * [Get Region](https://docs.medusajs.com/api/admin#regions_getregionsid) + * API route. + * + * @param id - The ID of the region to retrieve. + * @param query - Configure the fields and relations to retrieve in the region. + * @param headers - Headers to pass in the request. + * @returns The region's details. + * + * @example + * To retrieve a region by its ID: + * + * ```ts + * sdk.admin.region.retrieve("region_123") + * .then(({ region }) => { + * console.log(region) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.region.retrieve("region_123", { + * fields: "id,*countries" + * }) + * .then(({ region }) => { + * console.log(region) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve(id: string, query?: SelectParams, headers?: ClientHeaders) { - return await this.client.fetch<{ region: HttpTypes.AdminRegion }>( + return await this.client.fetch( `/admin/regions/${id}`, { query, @@ -74,6 +192,21 @@ export class Region { ) } + /** + * This method deletes a region by ID. It sends a request to the + * [Delete Region](https://docs.medusajs.com/api/admin#regions_deleteregionsid) + * API route. + * + * @param id - The ID of the region to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.region.delete("region_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/regions/${id}`, diff --git a/packages/core/js-sdk/src/admin/reservation.ts b/packages/core/js-sdk/src/admin/reservation.ts index 74fcf6b802..e87e58e1af 100644 --- a/packages/core/js-sdk/src/admin/reservation.ts +++ b/packages/core/js-sdk/src/admin/reservation.ts @@ -14,6 +14,39 @@ class Reservation { this.client = client } + /** + * This method retrieves a reservation by ID. It sends a request to the + * [Get Reservation](https://docs.medusajs.com/api/admin#reservations_getreservationsid) + * API route. + * + * @param id - The reservation's ID. + * @param query - Configure the fields and relations to retrieve in the reservation. + * @param headers - Headers to pass in the request. + * @returns The reservation's details. + * + * @example + * To retrieve a reservation by its ID: + * + * ```ts + * sdk.admin.reservation.retrieve("res_123") + * .then(({ reservation }) => { + * console.log(reservation) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.reservation.retrieve("res_123", { + * fields: "id,name" + * }) + * .then(({ reservation }) => { + * console.log(reservation) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.AdminReservationParams, @@ -29,6 +62,53 @@ class Reservation { ) } + /** + * This method retrieves a list of reservations. It sends a request to the + * [List Reservations](https://docs.medusajs.com/api/admin#reservations_getreservations) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of reservations. + * + * @example + * To retrieve the list of reservations: + * + * ```ts + * sdk.admin.reservation.list() + * .then(({ reservations, count, limit, offset }) => { + * console.log(reservations) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.reservation.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ reservations, count, limit, offset }) => { + * console.log(reservations) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each reservation: + * + * ```ts + * sdk.admin.reservation.list({ + * fields: "id,*inventory_item" + * }) + * .then(({ reservations, count, limit, offset }) => { + * console.log(reservations) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminGetReservationsParams, headers?: ClientHeaders @@ -43,6 +123,26 @@ class Reservation { ) } + /** + * This method creates a reservation. It sends a request to the + * [Create Reservation](https://docs.medusajs.com/api/admin#reservations_postreservations) + * API route. + * + * @param body - The details of the reservation to create. + * @param query - Configure the fields and relations to retrieve in the reservation. + * @param headers - Headers to pass in the request. + * @returns The reservation's details. + * + * @example + * sdk.admin.reservation.create({ + * inventory_item_id: "iitem_123", + * location_id: "sloc_123", + * quantity: 10, + * }) + * .then(({ reservation }) => { + * console.log(reservation) + * }) + */ async create( body: HttpTypes.AdminCreateReservation, query?: HttpTypes.AdminGetReservationsParams, @@ -59,6 +159,25 @@ class Reservation { ) } + /** + * This method updates a reservation. It sends a request to the + * [Update Reservation](https://docs.medusajs.com/api/admin#reservations_postreservationsid) + * API route. + * + * @param id - The reservation's ID. + * @param body - The details of the reservation to update. + * @param query - Configure the fields and relations to retrieve in the reservation. + * @param headers - Headers to pass in the request. + * @returns The reservation's details. + * + * @example + * sdk.admin.reservation.update("res_123", { + * quantity: 20, + * }) + * .then(({ reservation }) => { + * console.log(reservation) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateReservation, @@ -76,6 +195,21 @@ class Reservation { ) } + /** + * This method deletes a reservation by ID. It sends a request to the + * [Delete Reservation](https://docs.medusajs.com/api/admin#reservations_deletereservationsid) + * API route. + * + * @param id - The reservation's ID. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.reservation.delete("res_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/reservations/${id}`, diff --git a/packages/core/js-sdk/src/admin/return-reason.ts b/packages/core/js-sdk/src/admin/return-reason.ts index cdd51aec37..7caf516393 100644 --- a/packages/core/js-sdk/src/admin/return-reason.ts +++ b/packages/core/js-sdk/src/admin/return-reason.ts @@ -15,6 +15,53 @@ export class ReturnReason { this.client = client } + /** + * This method retrieves a list of return reasons. It sends a request to the + * [List Return Reasons](https://docs.medusajs.com/api/admin#return-reasons_returnreason_schema) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of return reasons. + * + * @example + * To retrieve the list of return reasons: + * + * ```ts + * sdk.admin.returnReason.list() + * .then(({ return_reasons, count, limit, offset }) => { + * console.log(return_reasons) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.returnReason.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ return_reasons, count, limit, offset }) => { + * console.log(return_reasons) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each return reason: + * + * ```ts + * sdk.admin.returnReason.list({ + * fields: "id,value" + * }) + * .then(({ return_reasons, count, limit, offset }) => { + * console.log(return_reasons) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminReturnReasonListParams, headers?: ClientHeaders @@ -28,6 +75,39 @@ export class ReturnReason { ) } + /** + * This method retrieves a return reason by ID. It sends a request to the + * [Get Return Reason](https://docs.medusajs.com/api/admin#return-reasons_getreturnreasonsid) + * API route. + * + * @param id - The return reason's ID. + * @param query - Configure the fields and relations to retrieve in the return reason. + * @param headers - Headers to pass in the request. + * @returns The return reason's details. + * + * @example + * To retrieve a return reason by its ID: + * + * ```ts + * sdk.admin.returnReason.retrieve("ret_123") + * .then(({ return_reason }) => { + * console.log(return_reason) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.returnReason.retrieve("ret_123", { + * fields: "id,value" + * }) + * .then(({ return_reason }) => { + * console.log(return_reason) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.AdminReturnReasonParams, @@ -42,6 +122,25 @@ export class ReturnReason { ) } + /** + * This method creates a return reason. It sends a request to the + * [Create Return Reason](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasons) + * API route. + * + * @param body - The details of the return reason to create. + * @param query - Configure the fields and relations to retrieve in the return reason. + * @param headers - Headers to pass in the request. + * @returns The return reason's details. + * + * @example + * sdk.admin.returnReason.create({ + * value: "refund", + * label: "Refund", + * }) + * .then(({ return_reason }) => { + * console.log(return_reason) + * }) + */ async create( body: HttpTypes.AdminCreateReturnReason, query?: HttpTypes.AdminReturnReasonParams, @@ -58,6 +157,26 @@ export class ReturnReason { ) } + /** + * This method updates a return reason. It sends a request to the + * [Update Return Reason](https://docs.medusajs.com/api/admin#return-reasons_postreturnreasonsid) + * API route. + * + * @param id - The return reason's ID. + * @param body - The details of the return reason to update. + * @param query - Configure the fields and relations to retrieve in the return reason. + * @param headers - Headers to pass in the request. + * @returns The return reason's details. + * + * @example + * sdk.admin.returnReason.update("ret_123", { + * value: "refund", + * label: "Refund", + * }) + * .then(({ return_reason }) => { + * console.log(return_reason) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateReturnReason, @@ -75,6 +194,22 @@ export class ReturnReason { ) } + /** + * This method deletes a return reason. It sends a request to the + * [Delete Return Reason](https://docs.medusajs.com/api/admin#return-reasons_deletereturnreasonsid) + * API route. + * + * @param id - The return reason's ID. + * @param query - Query parameters to pass to the request. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.returnReason.delete("ret_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete( id: string, query?: HttpTypes.AdminReturnReasonParams, diff --git a/packages/core/js-sdk/src/admin/return.ts b/packages/core/js-sdk/src/admin/return.ts index ae862a26b1..31266f34a7 100644 --- a/packages/core/js-sdk/src/admin/return.ts +++ b/packages/core/js-sdk/src/admin/return.ts @@ -15,6 +15,53 @@ export class Return { this.client = client } + /** + * This method retrieves a list of returns. It sends a request to the + * [List Returns](https://docs.medusajs.com/api/admin#returns_getreturns) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of returns. + * + * @example + * To retrieve the list of returns: + * + * ```ts + * sdk.admin.return.list() + * .then(({ returns, count, limit, offset }) => { + * console.log(returns) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.return.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ returns, count, limit, offset }) => { + * console.log(returns) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each return: + * + * ```ts + * sdk.admin.return.list({ + * fields: "id,*items" + * }) + * .then(({ returns, count, limit, offset }) => { + * console.log(returns) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list(query?: HttpTypes.AdminReturnFilters, headers?: ClientHeaders) { return await this.client.fetch( `/admin/returns`, @@ -25,6 +72,39 @@ export class Return { ) } + /** + * This method retrieves a return by ID. It sends a request to the + * [Get Return](https://docs.medusajs.com/api/admin#returns_getreturnsid) + * API route. + * + * @param id - The ID of the return to retrieve. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * To retrieve a return by its ID: + * + * ```ts + * sdk.admin.return.retrieve("return_123") + * .then(({ return }) => { + * console.log(return) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.return.retrieve("return_123", { + * fields: "id,*items" + * }) + * .then(({ return }) => { + * console.log(return) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve(id: string, query?: SelectParams, headers?: ClientHeaders) { return await this.client.fetch( `/admin/returns/${id}`, @@ -35,6 +115,24 @@ export class Return { ) } + /** + * This method initiates a return request by creating a return. It sends a request to the + * [Create Return](https://docs.medusajs.com/api/admin#returns_postreturns) + * API route. + * + * @param body - The details of the return to create. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.initiateRequest({ + * order_id: "order_123", + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async initiateRequest( body: HttpTypes.AdminInitiateReturnRequest, query?: HttpTypes.SelectParams, @@ -51,6 +149,22 @@ export class Return { ) } + /** + * This method cancels a return. It sends a request to the + * [Cancel Return](https://docs.medusajs.com/api/admin#returns_postreturnsidcancel) + * API route. + * + * @param id - The ID of the return to cancel. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.cancel("return_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async cancel( id: string, query?: HttpTypes.SelectParams, @@ -66,6 +180,22 @@ export class Return { ) } + /** + * This method cancels a return request. It sends a request to the + * [Cancel Return Request](https://docs.medusajs.com/api/admin#returns_deletereturnsidrequest) + * API route. + * + * @param id - The ID of the return to cancel. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.cancelRequest("return_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async cancelRequest( id: string, query?: HttpTypes.SelectParams, @@ -81,6 +211,26 @@ export class Return { ) } + /** + * This method adds an item to a return request. It sends a request to the + * [Add Return Item](https://docs.medusajs.com/api/admin#returns_postreturnsidrequestitems) + * API route. + * + * @param id - The ID of the return to add the item to. + * @param body - The details of the item to add to the return. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.addReturnItem("return_123", { + * id: "orlitem_123", + * quantity: 1, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async addReturnItem( id: string, body: HttpTypes.AdminAddReturnItems, @@ -98,6 +248,31 @@ export class Return { ) } + /** + * This method updates an item in a return request by the ID of the item's `RETURN_ITEM` action. + * Every item has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. For example, + * `item.actions.find((action) => action.action === "RETURN_ITEM")?.id` is the ID of an item's `RETURN_ITEM` action. + * + * This method sends a request to the + * [Update Requested Return Item](https://docs.medusajs.com/api/admin#returns_postreturnsidrequestitemsaction_id) + * API route. + * + * @param id - The ID of the return to update the item in. + * @param actionId - The ID of the item's `RETURN_ITEM` action. + * @param body - The details of the item to update. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.updateReturnItem("return_123", "orchach_123", { + * quantity: 2, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async updateReturnItem( id: string, actionId: string, @@ -116,6 +291,29 @@ export class Return { ) } + /** + * This method removes an item from a return request by the ID of the item's `RETURN_ITEM` action. + * + * Every item has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. For example, + * `item.actions.find((action) => action.action === "RETURN_ITEM")?.id` is the ID of an item's `RETURN_ITEM` action. + * + * This method sends a request to the + * [Remove Item from Return](https://docs.medusajs.com/api/admin#returns_deletereturnsidrequestitemsaction_id) + * API route. + * + * @param id - The ID of the return to remove the item from. + * @param actionId - The ID of the item's `RETURN_ITEM` action. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.removeReturnItem("return_123", "orchach_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async removeReturnItem( id: string, actionId: string, @@ -132,6 +330,25 @@ export class Return { ) } + /** + * This method adds a shipping method to a return request. It sends a request to the + * [Add Shipping Method to Return](https://docs.medusajs.com/api/admin#returns_postreturnsidshippingmethod) + * API route. + * + * @param id - The ID of the return to add the shipping method to. + * @param body - The details of the shipping method to add to the return. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.addReturnShipping("return_123", { + * shipping_option_id: "so_123", + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async addReturnShipping( id: string, body: HttpTypes.AdminAddReturnShipping, @@ -149,6 +366,34 @@ export class Return { ) } + /** + * This method updates a shipping method in a return request by the ID of the shipping method's `SHIPPING_ADD` action. + * + * Every shipping method has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. + * + * For example, `shipping_method.actions.find((action) => action.action === "SHIPPING_ADD")?.id` is + * the ID of a shipping method's `SHIPPING_ADD` action. + * + * This method sends a request to the + * [Update Shipping Method in Return](https://docs.medusajs.com/api/admin#returns_postreturnsidshippingmethodaction_id) + * API route. + * + * @param id - The ID of the return to update the shipping method in. + * @param actionId - The ID of the shipping method's `SHIPPING_ADD` action. + * @param body - The details of the shipping method to update. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.updateReturnShipping("return_123", "orchach_123", { + * custom_amount: 100, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async updateReturnShipping( id: string, actionId: string, @@ -167,6 +412,31 @@ export class Return { ) } + /** + * This method removes a shipping method from a return request by the ID of the shipping method's `SHIPPING_ADD` action. + * + * Every shipping method has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. + * + * For example, `shipping_method.actions.find((action) => action.action === "SHIPPING_ADD")?.id` is + * the ID of a shipping method's `SHIPPING_ADD` action. + * + * This method sends a request to the + * [Remove Shipping Method from Return](https://docs.medusajs.com/api/admin#returns_deletereturnsidshippingmethodaction_id) + * API route. + * + * @param id - The ID of the return to remove the shipping method from. + * @param actionId - The ID of the shipping method's `SHIPPING_ADD` action. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.deleteReturnShipping("return_123", "orchach_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async deleteReturnShipping( id: string, actionId: string, @@ -183,6 +453,25 @@ export class Return { ) } + /** + * This method updates a return request. It sends a request to the + * [Update Return](https://docs.medusajs.com/api/admin#returns_postreturnsid) + * API route. + * + * @param id - The ID of the return to update. + * @param body - The details of the return to update. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.updateRequest("return_123", { + * location_id: "sloc_123", + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async updateRequest( id: string, body: HttpTypes.AdminUpdateReturnRequest, @@ -200,6 +489,30 @@ export class Return { ) } + /** + * This method confirms a return request. The return's changes are applied on the inventory quantity of the return + * items and the order only after the return has been confirmed as received using the + * [Confirm Return Receival](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveconfirm) + * API route. + * + * This method sends a request to the + * [Confirm Return Request](https://docs.medusajs.com/api/admin#returns_postreturnsidrequest) + * API route. + * + * @param id - The ID of the return to confirm. + * @param body - The details of the return to confirm. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.confirmRequest("return_123", { + * no_notification: true, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async confirmRequest( id: string, body: HttpTypes.AdminConfirmReturnRequest, @@ -217,6 +530,25 @@ export class Return { ) } + /** + * This method starts the return receival process. It sends a request to the + * [Start Return Receival](https://docs.medusajs.com/api/admin#returns_postreturnsidreceive) + * API route. + * + * @param id - The ID of the return to start the receival process. + * @param body - The details of the return to start the receival process. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.initiateReceive("return_123", { + * internal_note: "Return received by the customer", + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async initiateReceive( id: string, body: HttpTypes.AdminInitiateReceiveReturn, @@ -234,6 +566,29 @@ export class Return { ) } + /** + * This method adds received items to a return. These items will have the action `RECEIVE_RETURN_ITEM`. + * + * The method sends a request to the + * [Add Received Items](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveitems) + * API route. + * + * @param id - The ID of the return to add the received items to. + * @param body - The details of the received items to add to the return. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.receiveItems("return_123", { + * items: [ + * { id: "item_123", quantity: 1 }, + * ], + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async receiveItems( id: string, body: HttpTypes.AdminReceiveItems, @@ -251,6 +606,34 @@ export class Return { ) } + /** + * This method updates a received item in the return by the ID of the item's `RECEIVE_RETURN_ITEM` action. + * + * Every item has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. + * + * For example, `received_item.actions.find((action) => action.action === "RECEIVE_RETURN_ITEM")?.id` is + * the ID of a received item's `RECEIVE_RETURN_ITEM` action. + * + * This method sends a request to the + * [Update Received Item](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveitemsaction_id) + * API route. + * + * @param id - The ID of the return to update the received item in. + * @param actionId - The ID of the received item's `RECEIVE_RETURN_ITEM` action. + * @param body - The details of the received item to update. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.updateReceiveItem("return_123", "orchach_123", { + * quantity: 2, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async updateReceiveItem( id: string, actionId: string, @@ -269,6 +652,31 @@ export class Return { ) } + /** + * This method removes a received item from the return by the ID of the item's `RECEIVE_RETURN_ITEM` action. + * + * Every item has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. + * + * For example, `received_item.actions.find((action) => action.action === "RECEIVE_RETURN_ITEM")?.id` is + * the ID of a received item's `RECEIVE_RETURN_ITEM` action. + * + * This method sends a request to the + * [Remove Received Item](https://docs.medusajs.com/api/admin#returns_deletereturnsidreceiveitemsaction_id) + * API route. + * + * @param id - The ID of the return to remove the received item from. + * @param actionId - The ID of the received item's `RECEIVE_RETURN_ITEM` action. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.removeReceiveItem("return_123", "orchach_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async removeReceiveItem( id: string, actionId: string, @@ -285,6 +693,32 @@ export class Return { ) } + /** + * This method adds damaged items to the return. These items will have the action `RECEIVE_DAMAGED_RETURN_ITEM`. + * + * A damaged item's quantity is not added back to the associated inventory item's quantity in the + * stock location where the return is initiated from. + * + * The method sends a request to the + * [Add Damaged Items](https://docs.medusajs.com/api/admin#returns_postreturnsiddismissitems) + * API route. + * + * @param id - The ID of the return to add the damaged items to. + * @param body - The details of the damaged items to add to the return. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.dismissItems("return_123", { + * items: [ + * { id: "orli_123", quantity: 1 }, + * ], + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async dismissItems( id: string, body: HttpTypes.AdminDismissItems, @@ -302,6 +736,34 @@ export class Return { ) } + /** + * This method updates a damaged item in the return by the ID of the item's `RECEIVE_DAMAGED_RETURN_ITEM` action. + * + * Every item has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. + * + * For example, `item.actions.find((action) => action.action === "RECEIVE_DAMAGED_RETURN_ITEM")?.id` is + * the ID of a damaged item's `RECEIVE_DAMAGED_RETURN_ITEM` action. + * + * This method sends a request to the + * [Update Damaged Item](https://docs.medusajs.com/api/admin#returns_postreturnsiddismissitemsaction_id) + * API route. + * + * @param id - The ID of the return to update the damaged item in. + * @param actionId - The ID of the damaged item's `RECEIVE_DAMAGED_RETURN_ITEM` action. + * @param body - The details of the damaged item to update. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.updateDismissItem("return_123", "orchach_123", { + * quantity: 2, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async updateDismissItem( id: string, actionId: string, @@ -320,6 +782,31 @@ export class Return { ) } + /** + * This method removes a damaged item from the return by the ID of the item's `RECEIVE_DAMAGED_RETURN_ITEM` action. + * + * Every item has an `actions` property, whose value is an array of actions. You can check the action's name + * using its `action` property, and use the value of the `id` property. + * + * For example, `item.actions.find((action) => action.action === "RECEIVE_DAMAGED_RETURN_ITEM")?.id` is + * the ID of a damaged item's `RECEIVE_DAMAGED_RETURN_ITEM` action. + * + * This method sends a request to the + * [Remove Damaged Item](https://docs.medusajs.com/api/admin#returns_deletereturnsiddismissitemsaction_id) + * API route. + * + * @param id - The ID of the return to remove the damaged item from. + * @param actionId - The ID of the damaged item's `RECEIVE_DAMAGED_RETURN_ITEM` action. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.removeDismissItem("return_123", "orchach_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async removeDismissItem( id: string, actionId: string, @@ -336,6 +823,25 @@ export class Return { ) } + /** + * This method confirms the return receival. It sends a request to the + * [Confirm Return Receival](https://docs.medusajs.com/api/admin#returns_postreturnsidreceiveconfirm) + * API route. + * + * @param id - The ID of the return to confirm the receival of. + * @param body - The details of the receival confirmation. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.confirmReceive("return_123", { + * no_notification: true, + * }) + * .then(({ return }) => { + * console.log(return) + * }) + */ async confirmReceive( id: string, body: HttpTypes.AdminConfirmReceiveReturn, @@ -353,6 +859,22 @@ export class Return { ) } + /** + * This method cancels a return receival. It sends a request to the + * [Cancel Return Receival](https://docs.medusajs.com/api/admin#returns_deletereturnsidreceive) + * API route. + * + * @param id - The ID of the return to cancel the receival of. + * @param query - Configure the fields and relations to retrieve in the return. + * @param headers - Headers to pass in the request. + * @returns The return's details. + * + * @example + * sdk.admin.return.cancelReceive("return_123") + * .then(({ return }) => { + * console.log(return) + * }) + */ async cancelReceive( id: string, query?: HttpTypes.SelectParams, diff --git a/packages/core/js-sdk/src/admin/sales-channel.ts b/packages/core/js-sdk/src/admin/sales-channel.ts index 88c6ea2d54..70c29879ff 100644 --- a/packages/core/js-sdk/src/admin/sales-channel.ts +++ b/packages/core/js-sdk/src/admin/sales-channel.ts @@ -14,6 +14,24 @@ export class SalesChannel { this.client = client } + /** + * This method creates a new sales channel. It sends a request to the + * [Create Sales Channel](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannels) + * API route. + * + * @param body - The details of the sales channel to create. + * @param query - Configure the fields and relations to retrieve in the sales channel. + * @param headers - Headers to pass in the request. + * @returns The sales channel's details. + * + * @example + * sdk.admin.salesChannel.create({ + * name: "Storefront", + * }) + * .then(({ salesChannel }) => { + * console.log(salesChannel) + * }) + */ async create( body: HttpTypes.AdminCreateSalesChannel, query?: HttpTypes.SelectParams, @@ -30,6 +48,28 @@ export class SalesChannel { ) } + /** + * This method updates a sales channel. It sends a request to the + * [Update Sales Channel](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelsid) + * API route. + * + * @param id - The ID of the sales channel to update. + * @param body - The details of the sales channel to update. + * @param query - Configure the fields and relations to retrieve in the sales channel. + * @param headers - Headers to pass in the request. + * @returns The sales channel's details. + * + * @example + * sdk.admin.salesChannel.update( + * "sc_123", + * { + * name: "Storefront", + * } + * ) + * .then(({ salesChannel }) => { + * console.log(salesChannel) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateSalesChannel, @@ -47,6 +87,21 @@ export class SalesChannel { ) } + /** + * This method deletes a sales channel. It sends a request to the + * [Delete Sales Channel](https://docs.medusajs.com/api/admin#sales-channels_deletesaleschannelsid) + * API route. + * + * @param id - The ID of the sales channel to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.salesChannel.delete("sc_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/sales-channels/${id}`, @@ -57,6 +112,39 @@ export class SalesChannel { ) } + /** + * This method retrieves a sales channel. It sends a request to the + * [Retrieve Sales Channel](https://docs.medusajs.com/api/admin#sales-channels_getsaleschannelsid) + * API route. + * + * @param id - The ID of the sales channel to retrieve. + * @param query - Configure the fields and relations to retrieve in the sales channel. + * @param headers - Headers to pass in the request. + * @returns The sales channel's details. + * + * @example + * To retrieve a sales channel by its ID: + * + * ```ts + * sdk.admin.salesChannel.retrieve("sc_123") + * .then(({ sales_channel }) => { + * console.log(sales_channel) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.salesChannel.retrieve("sc_123", { + * fields: "id,*products" + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.SelectParams, @@ -72,6 +160,53 @@ export class SalesChannel { ) } + /** + * This method retrieves a list of sales channels. It sends a request to the + * [List Sales Channels](https://docs.medusajs.com/api/admin#sales-channels_getsaleschannels) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of sales channels. + * + * @example + * To retrieve the list of sales channels: + * + * ```ts + * sdk.admin.salesChannel.list() + * .then(({ sales_channels, count, limit, offset }) => { + * console.log(sales_channels) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.salesChannel.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ sales_channels, count, limit, offset }) => { + * console.log(sales_channels) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each sales channel: + * + * ```ts + * sdk.admin.salesChannel.list({ + * fields: "id,*products" + * }) + * .then(({ sales_channels, count, limit, offset }) => { + * console.log(sales_channels) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminSalesChannelListParams, headers?: ClientHeaders @@ -86,6 +221,25 @@ export class SalesChannel { ) } + /** + * This method manages the products in a sales channel to add or remove them. It sends a request to the + * [Manage Products in Sales Channel](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelsidproducts) + * API route. + * + * @param id - The ID of the sales channel to manage the products for. + * @param body - The details of the products to add or remove from the sales channel. + * @param headers - Headers to pass in the request. + * @returns The sales channel's details. + * + * @example + * sdk.admin.salesChannel.updateProducts("sc_123", { + * add: ["prod_123", "prod_456"], + * remove: ["prod_789"] + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel) + * }) + */ async updateProducts( id: string, body: HttpTypes.AdminUpdateSalesChannelProducts, @@ -101,6 +255,25 @@ export class SalesChannel { ) } + /** + * This method manages the products in a sales channel to add or remove them. It sends a request to the + * [Manage Products in Sales Channel](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelsidproducts) + * API route. + * + * @param id - The ID of the sales channel to manage the products for. + * @param body - The details of the products to add or remove from the sales channel. + * @param headers - Headers to pass in the request. + * @returns The sales channel's details. + * + * @example + * sdk.admin.salesChannel.batchProducts("sc_123", { + * add: ["prod_123", "prod_456"], + * remove: ["prod_789"] + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel) + * }) + */ async batchProducts( id: string, body: HttpTypes.AdminBatchLink, diff --git a/packages/core/js-sdk/src/admin/shipping-option.ts b/packages/core/js-sdk/src/admin/shipping-option.ts index 39bccca0d6..2fb5372d89 100644 --- a/packages/core/js-sdk/src/admin/shipping-option.ts +++ b/packages/core/js-sdk/src/admin/shipping-option.ts @@ -13,7 +13,25 @@ export class ShippingOption { constructor(client: Client) { this.client = client } - + /** + * This method creates a shipping option. It sends a request to the + * [Create Shipping Option](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptions) + * API route. + * + * @param body - The details of the shipping option to create. + * @param query - Configure the fields and relations to retrieve in the shipping option. + * @param headers - Headers to pass in the request. + * @returns The shipping option's details. + * + * @example + * sdk.admin.shippingOption.create({ + * name: "Standard Shipping", + * profile_id: "shp_123", + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option) + * }) + */ async create( body: HttpTypes.AdminCreateShippingOption, query?: HttpTypes.SelectParams, @@ -30,6 +48,39 @@ export class ShippingOption { ) } + /** + * This method retrieves a shipping option. It sends a request to the + * [Get Shipping Option](https://docs.medusajs.com/api/admin#shipping-options_getshippingoptionsid) + * API route. + * + * @param id - The ID of the shipping option to retrieve. + * @param query - Configure the fields and relations to retrieve in the shipping option. + * @param headers - Headers to pass in the request. + * @returns The shipping option's details. + * + * @example + * To retrieve a shipping option by its ID: + * + * ```ts + * sdk.admin.shippingOption.retrieve("so_123") + * .then(({ shipping_option }) => { + * console.log(shipping_option) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.shippingOption.retrieve("so_123", { + * fields: "id,*service_zone" + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.SelectParams, @@ -45,6 +96,25 @@ export class ShippingOption { ) } + /** + * This method updates a shipping option. It sends a request to the + * [Update Shipping Option](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsid) + * API route. + * + * @param id - The ID of the shipping option to update. + * @param body - The details of the shipping option to update. + * @param query - Configure the fields and relations to retrieve in the shipping option. + * @param headers - Headers to pass in the request. + * @returns The shipping option's details. + * + * @example + * sdk.admin.shippingOption.update("so_123", { + * name: "Standard Shipping", + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateShippingOption, @@ -62,6 +132,21 @@ export class ShippingOption { ) } + /** + * This method deletes a shipping option. It sends a request to the + * [Delete Shipping Option](https://docs.medusajs.com/api/admin#shipping-options_deleteshippingoptionsid) + * API route. + * + * @param id - The ID of the shipping option to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.shippingOption.delete("so_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/shipping-options/${id}`, @@ -72,6 +157,53 @@ export class ShippingOption { ) } + /** + * This method retrieves a list of shipping options. It sends a request to the + * [List Shipping Options](https://docs.medusajs.com/api/admin#shipping-options_getshippingoptions) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of shipping options. + * + * @example + * To retrieve the list of shipping options: + * + * ```ts + * sdk.admin.shippingOption.list() + * .then(({ shipping_options, count, limit, offset }) => { + * console.log(shipping_options) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.shippingOption.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ shipping_options, count, limit, offset }) => { + * console.log(shipping_options) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each shipping option: + * + * ```ts + * sdk.admin.shippingOption.list({ + * fields: "id,*service_zone" + * }) + * .then(({ shipping_options, count, limit, offset }) => { + * console.log(shipping_options) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminShippingOptionListParams, headers?: ClientHeaders @@ -86,6 +218,24 @@ export class ShippingOption { ) } + /** + * This method manages the rules of a shipping option to create, update, or remove them. It sends a request to the + * [Manage Rules of a Shipping Option](https://docs.medusajs.com/api/admin#shipping-options_postshippingoptionsidrulesbatch) + * API route. + * + * @param id - The ID of the shipping option to manage the rules for. + * @param body - The details of the shipping option rules to manage. + * @param headers - Headers to pass in the request. + * @returns The shipping option's details. + * + * @example + * sdk.admin.shippingOption.updateRules("so_123", { + * create: [{ attribute: "enabled_in_store", operator: "eq", value: "true" }], + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option) + * }) + */ async updateRules( id: string, body: HttpTypes.AdminUpdateShippingOptionRules, diff --git a/packages/core/js-sdk/src/admin/shipping-profile.ts b/packages/core/js-sdk/src/admin/shipping-profile.ts index aaacbd09af..f92b1ca5f7 100644 --- a/packages/core/js-sdk/src/admin/shipping-profile.ts +++ b/packages/core/js-sdk/src/admin/shipping-profile.ts @@ -14,6 +14,24 @@ export class ShippingProfile { this.client = client } + /** + * This method creates a new shipping profile. It sends a request to the + * [Create Shipping Profile](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofiles) + * API route. + * + * @param body - The details of the shipping profile to create. + * @param query - Configure the fields and relations to retrieve in the shipping profile. + * @param headers - Headers to pass in the request. + * @returns The shipping profile's details. + * + * @example + * sdk.admin.shippingProfile.create({ + * name: "Default Shipping Profile", + * }) + * .then(({ shipping_profile }) => { + * console.log(shipping_profile) + * }) + */ async create( body: HttpTypes.AdminCreateShippingProfile, query?: HttpTypes.SelectParams, @@ -30,6 +48,25 @@ export class ShippingProfile { ) } + /** + * This method updates a shipping profile. It sends a request to the + * [Update Shipping Profile](https://docs.medusajs.com/api/admin#shipping-profiles_postshippingprofilesid) + * API route. + * + * @param id - The ID of the shipping profile to update. + * @param body - The details of the shipping profile to update. + * @param query - Configure the fields and relations to retrieve in the shipping profile. + * @param headers - Headers to pass in the request. + * @returns The shipping profile's details. + * + * @example + * sdk.admin.shippingProfile.update("sp_123", { + * name: "Updated Shipping Profile", + * }) + * .then(({ shipping_profile }) => { + * console.log(shipping_profile) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateShippingProfile, @@ -47,6 +84,21 @@ export class ShippingProfile { ) } + /** + * This method deletes a shipping profile. It sends a request to the + * [Delete Shipping Profile](https://docs.medusajs.com/api/admin#shipping-profiles_deleteshippingprofilesid) + * API route. + * + * @param id - The ID of the shipping profile to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.shippingProfile.delete("sp_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/shipping-profiles/${id}`, @@ -57,6 +109,53 @@ export class ShippingProfile { ) } + /** + * This method retrieves a list of shipping profiles. It sends a request to the + * [List Shipping Profiles](https://docs.medusajs.com/api/admin#shipping-profiles_getshippingprofiles) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of shipping profiles. + * + * @example + * To retrieve the list of shipping profiles: + * + * ```ts + * sdk.admin.shippingProfile.list() + * .then(({ shipping_profiles, count, limit, offset }) => { + * console.log(shipping_profiles) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.shippingProfile.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ shipping_profiles, count, limit, offset }) => { + * console.log(shipping_profiles) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each shipping profile: + * + * ```ts + * sdk.admin.shippingProfile.list({ + * fields: "id,name" + * }) + * .then(({ shipping_profiles, count, limit, offset }) => { + * console.log(shipping_profiles) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminShippingProfileListParams, headers?: ClientHeaders @@ -71,6 +170,39 @@ export class ShippingProfile { ) } + /** + * This method retrieves a shipping profile. It sends a request to the + * [Get Shipping Profile](https://docs.medusajs.com/api/admin#shipping-profiles_getshippingprofilesid) + * API route. + * + * @param id - The ID of the shipping profile to retrieve. + * @param query - Configure the fields and relations to retrieve in the shipping profile. + * @param headers - Headers to pass in the request. + * @returns The shipping profile's details. + * + * @example + * To retrieve a shipping profile by its ID: + * + * ```ts + * sdk.admin.shippingProfile.retrieve("sp_123") + * .then(({ shipping_profile }) => { + * console.log(shipping_profile) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.shippingProfile.retrieve("sp_123", { + * fields: "id,name" + * }) + * .then(({ shipping_profile }) => { + * console.log(shipping_profile) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.SelectParams, diff --git a/packages/core/js-sdk/src/admin/stock-location.ts b/packages/core/js-sdk/src/admin/stock-location.ts index 87598566e3..36131d0768 100644 --- a/packages/core/js-sdk/src/admin/stock-location.ts +++ b/packages/core/js-sdk/src/admin/stock-location.ts @@ -14,6 +14,25 @@ export class StockLocation { this.client = client } + /** + * This method creates a new stock location. It sends a request to the + * [Create Stock Location](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations) + * API route. + * + * @param body - The details of the stock location to create. + * @param query - Configure the fields and relations to retrieve in the stock location. + * @param headers - Headers to pass in the request. + * @returns The stock location's details. + * + * @example + * sdk.admin.stockLocation.create({ + * name: "Main Warehouse", + * address_id: "addr_123", + * }) + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + */ async create( body: HttpTypes.AdminCreateStockLocation, query?: SelectParams, @@ -30,6 +49,25 @@ export class StockLocation { ) } + /** + * This method updates a stock location. It sends a request to the + * [Update Stock Location](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsid) + * API route. + * + * @param id - The ID of the stock location to update. + * @param body - The details of the stock location to update. + * @param query - Configure the fields and relations to retrieve in the stock location. + * @param headers - Headers to pass in the request. + * @returns The stock location's details. + * + * @example + * sdk.admin.stockLocation.update("sloc_123", { + * name: "European Warehouse", + * }) + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateStockLocation, @@ -47,6 +85,21 @@ export class StockLocation { ) } + /** + * This method deletes a stock location. It sends a request to the + * [Delete Stock Location](https://docs.medusajs.com/api/admin#stock-locations_deletestocklocationsid) + * API route. + * + * @param id - The ID of the stock location to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.stockLocation.delete("sloc_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/stock-locations/${id}`, @@ -57,6 +110,39 @@ export class StockLocation { ) } + /** + * This method retrieves a stock location. It sends a request to the + * [Get Stock Location](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsid) + * API route. + * + * @param id - The ID of the stock location to retrieve. + * @param query - Configure the fields and relations to retrieve in the stock location. + * @param headers - Headers to pass in the request. + * @returns The stock location's details. + * + * @example + * To retrieve a stock location by its ID: + * + * ```ts + * sdk.admin.stockLocation.retrieve("sloc_123") + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.stockLocation.retrieve("sloc_123", { + * fields: "id,*sales_channels" + * }) + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve(id: string, query?: SelectParams, headers?: ClientHeaders) { return await this.client.fetch( `/admin/stock-locations/${id}`, @@ -68,6 +154,53 @@ export class StockLocation { ) } + /** + * This method retrieves a list of stock locations. It sends a request to the + * [List Stock Locations](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of stock locations. + * + * @example + * To retrieve the list of stock locations: + * + * ```ts + * sdk.admin.stockLocation.list() + * .then(({ stock_locations, count, limit, offset }) => { + * console.log(stock_locations) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.stockLocation.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ stock_locations, count, limit, offset }) => { + * console.log(stock_locations) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each stock location: + * + * ```ts + * sdk.admin.stockLocation.list({ + * fields: "id,*sales_channels" + * }) + * .then(({ stock_locations, count, limit, offset }) => { + * console.log(stock_locations) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminStockLocationListParams, headers?: ClientHeaders @@ -82,6 +215,25 @@ export class StockLocation { ) } + /** + * This method manages the sales channels of a stock location by adding or removing them. It sends a request to the + * [Manage Stock Location Sales Channels](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsidsaleschannels) + * API route. + * + * @param id - The ID of the stock location to update the sales channels for. + * @param body - The details of the sales channels to update. + * @param headers - Headers to pass in the request. + * @returns The stock location's details. + * + * @example + * sdk.admin.stockLocation.updateSalesChannels("sloc_123", { + * add: ["sc_123"], + * remove: ["sc_456"], + * }) + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + */ async updateSalesChannels( id: string, body: HttpTypes.AdminUpdateStockLocationSalesChannels, @@ -97,6 +249,25 @@ export class StockLocation { ) } + /** + * This method adds a new fulfillment set to a stock location. It sends a request to the + * [Add Fulfillment Set to Stock Location](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsidfulfillmentsets) + * API route. + * + * @param id - The ID of the stock location to add the fulfillment set to. + * @param body - The details of the fulfillment set to add. + * @param headers - Headers to pass in the request. + * @returns The stock location's details. + * + * @example + * sdk.admin.stockLocation.createFulfillmentSet("sloc_123", { + * name: "Shipping", + * type: "shipping", + * }) + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + */ async createFulfillmentSet( id: string, body: HttpTypes.AdminCreateStockLocationFulfillmentSet, @@ -112,6 +283,25 @@ export class StockLocation { ) } + /** + * This method manages the fulfillment providers of a stock location by adding or removing them. It sends a request to the + * [Manage Fulfillment Providers of Stock Location](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsidfulfillmentproviders) + * API route. + * + * @param id - The ID of the stock location to manage the fulfillment providers for. + * @param body - The details of the fulfillment providers to manage. + * @param headers - Headers to pass in the request. + * @returns The stock location's details. + * + * @example + * sdk.admin.stockLocation.updateFulfillmentProviders("sloc_123", { + * add: ["fp_manual_manual"], + * remove: ["fp_shipstation_shipstation"], + * }) + * .then(({ stock_location }) => { + * console.log(stock_location) + * }) + */ async updateFulfillmentProviders( id: string, body: HttpTypes.AdminBatchLink, diff --git a/packages/core/js-sdk/src/admin/store.ts b/packages/core/js-sdk/src/admin/store.ts index 7183e71a93..000317bac1 100644 --- a/packages/core/js-sdk/src/admin/store.ts +++ b/packages/core/js-sdk/src/admin/store.ts @@ -14,6 +14,39 @@ export class Store { this.client = client } + /** + * This method retrieves a store by its ID. It sends a request to the + * [Get Store](https://docs.medusajs.com/api/admin#stores_getstoresid) + * API route. + * + * @param id - The ID of the store to retrieve. + * @param query - Configure the fields and relations to retrieve in the store. + * @param headers - Headers to pass in the request. + * @returns The store's details. + * + * @example + * To retrieve a store by its ID: + * + * ```ts + * sdk.admin.store.retrieve("store_123") + * .then(({ store }) => { + * console.log(store) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.store.retrieve("store_123", { + * fields: "id,*supported_currencies" + * }) + * .then(({ store }) => { + * console.log(store) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.AdminStoreParams, @@ -29,6 +62,53 @@ export class Store { ) } + /** + * This method retrieves a list of stores. It sends a request to the + * [List Stores](https://docs.medusajs.com/api/admin#stores_getstores) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of stores. + * + * @example + * To retrieve the list of stores: + * + * ```ts + * sdk.admin.store.list() + * .then(({ stores, count, limit, offset }) => { + * console.log(stores) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.store.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ stores, count, limit, offset }) => { + * console.log(stores) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each store: + * + * ```ts + * sdk.admin.store.list({ + * fields: "id,*supported_currencies" + * }) + * .then(({ stores, count, limit, offset }) => { + * console.log(stores) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list(query?: HttpTypes.AdminStoreListParams, headers?: ClientHeaders) { return await this.client.fetch( `/admin/stores`, @@ -40,6 +120,25 @@ export class Store { ) } + /** + * This method updates a store. It sends a request to the + * [Update Store](https://docs.medusajs.com/api/admin#stores_poststoresid) + * API route. + * + * @param id - The ID of the store to update. + * @param body - The details of the store to update. + * @param query - Configure the fields and relations to retrieve in the store. + * @param headers - Headers to pass in the request. + * @returns The store's details. + * + * @example + * sdk.admin.store.update("store_123", { + * name: "My Store", + * }) + * .then(({ store }) => { + * console.log(store) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateStore, diff --git a/packages/core/js-sdk/src/admin/tax-rate.ts b/packages/core/js-sdk/src/admin/tax-rate.ts index 79e56c62f8..0ce2f41f9c 100644 --- a/packages/core/js-sdk/src/admin/tax-rate.ts +++ b/packages/core/js-sdk/src/admin/tax-rate.ts @@ -16,6 +16,27 @@ export class TaxRate { this.client = client } + /** + * This method creates a tax rate. It sends a request to the + * [Create Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_posttaxrates) + * API route. + * + * @param body - The details of the tax rate to create. + * @param query - Configure the fields and relations to retrieve in the tax rate. + * @param headers - Headers to pass in the request. + * @returns The tax rate's details. + * + * @example + * sdk.admin.taxRate.create({ + * name: "VAT", + * tax_region_id: "txreg_123", + * code: "VAT", + * rate: 2, // 2% + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate) + * }) + */ async create( body: HttpTypes.AdminCreateTaxRate, query?: HttpTypes.SelectParams, @@ -29,6 +50,26 @@ export class TaxRate { }) } + /** + * This method updates a tax rate. It sends a request to the + * [Update Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_posttaxratesid) + * API route. + * + * @param id - The ID of the tax rate to update. + * @param body - The details of the tax rate to update. + * @param query - Configure the fields and relations to retrieve in the tax rate. + * @param headers - Headers to pass in the request. + * @returns The tax rate's details. + * + * @example + * sdk.admin.taxRate.update("txrat_123", { + * name: "VAT", + * code: "VAT", + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateTaxRate, @@ -46,6 +87,21 @@ export class TaxRate { ) } + /** + * This method deletes a tax rate. It sends a request to the + * [Delete Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_deletetaxratesid) + * API route. + * + * @param id - The ID of the tax rate to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.taxRate.delete("txrat_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `${taxRateUrl}/${id}`, @@ -56,6 +112,39 @@ export class TaxRate { ) } + /** + * This method retrieves a tax rate. It sends a request to the + * [Get Tax Rate](https://docs.medusajs.com/api/admin#tax-rates_gettaxratesid) + * API route. + * + * @param id - The ID of the tax rate to retrieve. + * @param query - Configure the fields and relations to retrieve in the tax rate. + * @param headers - Headers to pass in the request. + * @returns The tax rate's details. + * + * @example + * To retrieve a tax rate by its ID: + * + * ```ts + * sdk.admin.taxRate.retrieve("txrat_123") + * .then(({ tax_rate }) => { + * console.log(tax_rate) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.taxRate.retrieve("txrat_123", { + * fields: "id,*tax_region" + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.SelectParams, @@ -71,6 +160,53 @@ export class TaxRate { ) } + /** + * This method retrieves a list of tax rates. It sends a request to the + * [List Tax Rates](https://docs.medusajs.com/api/admin#tax-rates_gettaxrates) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of tax rates. + * + * @example + * To retrieve the list of tax rates: + * + * ```ts + * sdk.admin.taxRate.list() + * .then(({ tax_rates, count, limit, offset }) => { + * console.log(tax_rates) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.taxRate.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ tax_rates, count, limit, offset }) => { + * console.log(tax_rates) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each tax rate: + * + * ```ts + * sdk.admin.taxRate.list({ + * fields: "id,*tax_region" + * }) + * .then(({ tax_rates, count, limit, offset }) => { + * console.log(tax_rates) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminTaxRateListParams, headers?: ClientHeaders diff --git a/packages/core/js-sdk/src/admin/tax-region.ts b/packages/core/js-sdk/src/admin/tax-region.ts index 5bd6cb39d7..f232af3b3b 100644 --- a/packages/core/js-sdk/src/admin/tax-region.ts +++ b/packages/core/js-sdk/src/admin/tax-region.ts @@ -4,7 +4,11 @@ import { ClientHeaders } from "../types" const taxRegionUrl = "/admin/tax-regions" -// TODO: Add support for updating a tax region +/** + * @privateRemarks + * + * TODO: Add support for updating a tax region + */ export class TaxRegion { /** * @ignore @@ -17,6 +21,31 @@ export class TaxRegion { this.client = client } + /** + * This method creates a tax region. It sends a request to the + * [Create Tax Region](https://docs.medusajs.com/api/admin#tax-regions_posttaxregions) + * API route. + * + * @param body - The details of the tax region to create. + * @param query - Configure the fields and relations to retrieve in the tax region. + * @param headers - Headers to pass in the request. + * @returns The tax region's details. + * + * @example + * sdk.admin.taxRegion.create({ + * country_code: "us", + * province_code: "ca", + * default_tax_rate: { + * code: "VAT", + * name: "VAT", + * rate: 20, // 20% + * is_combinable: true, + * }, + * }) + * .then(({ tax_region }) => { + * console.log(tax_region) + * }) + */ async create( body: HttpTypes.AdminCreateTaxRegion, query?: HttpTypes.SelectParams, @@ -33,6 +62,21 @@ export class TaxRegion { ) } + /** + * This method deletes a tax region. It sends a request to the + * [Delete Tax Region](https://docs.medusajs.com/api/admin#tax-regions_deletetaxregionsid) + * API route. + * + * @param id - The ID of the tax region to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.taxRegion.delete("txreg_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `${taxRegionUrl}/${id}`, @@ -43,6 +87,39 @@ export class TaxRegion { ) } + /** + * This method retrieves a tax region. It sends a request to the + * [Get Tax Region](https://docs.medusajs.com/api/admin#tax-regions_gettaxregionsid) + * API route. + * + * @param id - The ID of the tax region to retrieve. + * @param query - Configure the fields and relations to retrieve in the tax region. + * @param headers - Headers to pass in the request. + * @returns The tax region's details. + * + * @example + * To retrieve a tax region by its ID: + * + * ```ts + * sdk.admin.taxRegion.retrieve("txreg_123") + * .then(({ tax_region }) => { + * console.log(tax_region) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.taxRegion.retrieve("txreg_123", { + * fields: "id,*tax_rates" + * }) + * .then(({ tax_region }) => { + * console.log(tax_region) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.SelectParams, @@ -58,6 +135,53 @@ export class TaxRegion { ) } + /** + * This method retrieves a list of tax regions. It sends a request to the + * [List Tax Regions](https://docs.medusajs.com/api/admin#tax-regions_gettaxregions) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of tax regions. + * + * @example + * To retrieve the list of tax regions: + * + * ```ts + * sdk.admin.taxRegion.list() + * .then(({ tax_regions, count, limit, offset }) => { + * console.log(tax_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.admin.taxRegion.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ tax_regions, count, limit, offset }) => { + * console.log(tax_regions) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each tax region: + * + * ```ts + * sdk.admin.taxRegion.list({ + * fields: "id,*tax_rates" + * }) + * .then(({ tax_regions, count, limit, offset }) => { + * console.log(tax_regions) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminTaxRegionListParams, headers?: ClientHeaders diff --git a/packages/core/js-sdk/src/admin/upload.ts b/packages/core/js-sdk/src/admin/upload.ts index 36cb149dfa..5df11bf804 100644 --- a/packages/core/js-sdk/src/admin/upload.ts +++ b/packages/core/js-sdk/src/admin/upload.ts @@ -14,7 +14,38 @@ export class Upload { this.client = client } - // Note: The creation/upload flow be made more advanced, with support for streaming and progress, but for now we keep it simple + /** + * This method creates a new upload. It sends a request to the + * [Upload Files](https://docs.medusajs.com/api/admin#uploads_postuploads) + * API route. + * + * @param body - The details of the files to upload. + * @param query - Configure the fields and relations to retrieve in the uploaded files. + * @param headers - Headers to pass in the request. + * @returns The upload files' details. + * + * @privateRemarks + * + * Note: The creation/upload flow be made more advanced, with support for streaming and progress, but for now we keep it simple + * + * @example + * sdk.admin.upload.create( + * { + * files: [ + * // file uploaded as a base64 string + * { + * name: "test.txt", + * content: "test", // Should be the base64 content of the file + * }, + * // file uploaded as a File object + * new File(["test"], "test.txt", { type: "text/plain" }) + * ], + * } + * ) + * .then(({ files }) => { + * console.log(files) + * }) + */ async create( body: HttpTypes.AdminUploadFile, query?: SelectParams, @@ -39,7 +70,7 @@ export class Upload { }) } - return this.client.fetch<{ files: HttpTypes.AdminFile[] }>( + return this.client.fetch( `/admin/uploads`, { method: "POST", @@ -54,8 +85,24 @@ export class Upload { ) } + /** + * This method retrieves a file's details by its ID. It sends a request to the + * [Get File](https://docs.medusajs.com/api/admin#uploads_getuploadsid) + * API route. + * + * @param id - The ID of the file to retrieve. + * @param query - Query parameters to pass in the request. + * @param headers - Headers to pass in the request. + * @returns The file's details. + * + * @example + * sdk.admin.upload.retrieve("test.txt") + * .then(({ file }) => { + * console.log(file) + * }) + */ async retrieve(id: string, query?: SelectParams, headers?: ClientHeaders) { - return this.client.fetch<{ file: HttpTypes.AdminFile }>( + return this.client.fetch( `/admin/uploads/${id}`, { query, @@ -64,6 +111,21 @@ export class Upload { ) } + /** + * This method deletes a file by its ID from the configured File Module Provider. It sends a request to the + * [Delete File](https://docs.medusajs.com/api/admin#uploads_deleteuploadsid) + * API route. + * + * @param id - The ID of the file to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.upload.delete("test.txt") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return this.client.fetch( `/admin/uploads/${id}`, diff --git a/packages/core/js-sdk/src/admin/user.ts b/packages/core/js-sdk/src/admin/user.ts index 7cdd3f0b16..78c32ea2a4 100644 --- a/packages/core/js-sdk/src/admin/user.ts +++ b/packages/core/js-sdk/src/admin/user.ts @@ -14,6 +14,26 @@ export class User { this.client = client } + /** + * This method updates a user. It sends a request to the + * [Update User](https://docs.medusajs.com/api/admin#users_postusersid) + * API route. + * + * @param id - The ID of the user to update. + * @param body - The details of the user to update. + * @param query - Configure the fields and relations to retrieve in the tax region. + * @param headers - Headers to pass in the request. + * @returns The user's details. + * + * @example + * sdk.admin.user.update("user_123", { + * first_name: "John", + * last_name: "Doe", + * }) + * .then(({ user }) => { + * console.log(user) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateUser, @@ -31,6 +51,53 @@ export class User { ) } + /** + * This method retrieves a list of users. It sends a request to the + * [List Users](https://docs.medusajs.com/api/admin#users_getusers) + * API route. + * + * @param queryParams - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of users. + * + * @example + * To retrieve the list of users: + * + * ```ts + * sdk.admin.user.list() + * .then(({ users, count, limit, offset }) => { + * console.log(users) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.user.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ users, count, limit, offset }) => { + * console.log(users) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each user: + * + * ```ts + * sdk.admin.user.list({ + * fields: "id,email" + * }) + * .then(({ users, count, limit, offset }) => { + * console.log(users) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( queryParams?: HttpTypes.AdminUserListParams, headers?: ClientHeaders @@ -41,6 +108,39 @@ export class User { }) } + /** + * This method retrieves a user. It sends a request to the + * [Get User](https://docs.medusajs.com/api/admin#users_getusersid) + * API route. + * + * @param id - The ID of the user to retrieve. + * @param query - Configure the fields and relations to retrieve in the user. + * @param headers - Headers to pass in the request. + * @returns The user's details. + * + * @example + * To retrieve a user by its ID: + * + * ```ts + * sdk.admin.user.retrieve("user_123") + * .then(({ user }) => { + * console.log(user) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.user.retrieve("user_123", { + * fields: "id,email" + * }) + * .then(({ user }) => { + * console.log(user) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.AdminUserParams, @@ -55,6 +155,21 @@ export class User { ) } + /** + * This method deletes a user. It sends a request to the + * [Delete User](https://docs.medusajs.com/api/admin#users_deleteusersid) + * API route. + * + * @param id - The ID of the user to delete. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.user.delete("user_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return this.client.fetch( `/admin/users/${id}`, @@ -65,6 +180,38 @@ export class User { ) } + /** + * This method retrieves the currently authenticated user. It sends a request to the + * [Get Logged-In User](https://docs.medusajs.com/api/admin#users_getusersme) + * API route. + * + * @param query - Configure the fields and relations to retrieve in the user. + * @param headers - Headers to pass in the request. + * @returns The user's details. + * + * @example + * To retrieve the currently authenticated user: + * + * ```ts + * sdk.admin.user.me() + * .then(({ user }) => { + * console.log(user) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.user.me({ + * fields: "id,email" + * }) + * .then(({ user }) => { + * console.log(user) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async me(query?: HttpTypes.AdminUserParams, headers?: ClientHeaders) { return this.client.fetch(`/admin/users/me`, { query, diff --git a/packages/core/js-sdk/src/admin/workflow-execution.ts b/packages/core/js-sdk/src/admin/workflow-execution.ts index 17c4ab5624..bda4d1c6b7 100644 --- a/packages/core/js-sdk/src/admin/workflow-execution.ts +++ b/packages/core/js-sdk/src/admin/workflow-execution.ts @@ -14,6 +14,53 @@ export class WorkflowExecution { this.client = client } + /** + * This method retrieves a list of workflow executions. It sends a request to the + * [List Workflow Executions](https://docs.medusajs.com/api/admin#workflows-executions_getworkflowsexecutions) + * API route. + * + * @param queryParams - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The list of workflow executions. + * + * @example + * To retrieve the list of workflow executions: + * + * ```ts + * sdk.admin.workflowExecution.list() + * .then(({ workflow_executions, count, limit, offset }) => { + * console.log(workflow_executions) + * }) + * ``` + * + * To configure the pagination, pass the `limit` and `offset` query parameters. + * + * For example, to retrieve only 10 items and skip 10 items: + * + * ```ts + * sdk.admin.workflowExecution.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ workflow_executions, count, limit, offset }) => { + * console.log(workflow_executions) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each workflow execution: + * + * ```ts + * sdk.admin.workflowExecution.list({ + * fields: "id,name" + * }) + * .then(({ workflow_executions, count, limit, offset }) => { + * console.log(workflow_executions) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/admin#select-fields-and-relations). + */ async list( queryParams?: HttpTypes.AdminGetWorkflowExecutionsParams, headers?: ClientHeaders @@ -27,6 +74,21 @@ export class WorkflowExecution { ) } + /** + * This method retrieves a workflow execution by its ID. It sends a request to the + * [Get Workflow Execution](https://docs.medusajs.com/api/admin#workflows-executions_getworkflowsexecutionsworkflow_idtransaction_id) + * API route. + * + * @param id - The ID of the workflow execution to retrieve. + * @param headers - Headers to pass in the request. + * @returns The workflow execution's details. + * + * @example + * sdk.admin.workflowExecution.retrieve("wrk_123") + * .then(({ workflow_execution }) => { + * console.log(workflow_execution) + * }) + */ async retrieve(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/workflows-executions/${id}`, diff --git a/packages/core/js-sdk/src/store/index.ts b/packages/core/js-sdk/src/store/index.ts index acc0bca2da..1631981ae1 100644 --- a/packages/core/js-sdk/src/store/index.ts +++ b/packages/core/js-sdk/src/store/index.ts @@ -852,6 +852,25 @@ export class Store { ) }, + /** + * This method calculates the price of a shipping option in a cart, which is useful during checkout. + * It sends a request to the [Calculate Shipping Option Price](https://docs.medusajs.com/api/store#shipping-options_postshippingoptionsidcalculate) + * API route. + * + * @param id - The shipping option's ID. + * @param body - The price calculation's details. + * @param query - Configure the fields to retrieve in the shipping option. + * @param headers - Headers to pass in the request. + * @returns The shipping option's details. + * + * @example + * sdk.store.fulfillment.calculate("so_123", { + * cart_id: "cart_123" + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option) + * }) + */ calculate: async ( id: string, body: HttpTypes.StoreCalculateShippingOptionPrice, diff --git a/packages/core/types/src/http/common/request.ts b/packages/core/types/src/http/common/request.ts index ae737c7b59..e284868d88 100644 --- a/packages/core/types/src/http/common/request.ts +++ b/packages/core/types/src/http/common/request.ts @@ -27,11 +27,11 @@ export interface FindParams extends SelectParams { export interface AdminBatchLink { /** - * The items to create an association to. + * The IDs of the items to create an association to. */ add?: string[] /** - * The items to remove association from. + * The IDs of the items to remove the association from. */ remove?: string[] } diff --git a/packages/core/types/src/http/common/response.ts b/packages/core/types/src/http/common/response.ts index 29f679d527..281f48c885 100644 --- a/packages/core/types/src/http/common/response.ts +++ b/packages/core/types/src/http/common/response.ts @@ -41,11 +41,32 @@ export type PaginatedResponse = { } & T export type BatchResponse = { + /** + * The items that were created. + */ created: T[] + /** + * The items that were updated. + */ updated: T[] + /** + * Details of the items that were deleted. + */ deleted: { + /** + * The IDs of the items that were deleted. + */ ids: string[] + /** + * The type of the items that were deleted. + * + * @example + * "product" + */ object: string + /** + * Whether the items were deleted successfully. + */ deleted: boolean } } diff --git a/packages/core/types/src/http/file/admin/responses.ts b/packages/core/types/src/http/file/admin/responses.ts index 078955df5c..f9eaf5fc82 100644 --- a/packages/core/types/src/http/file/admin/responses.ts +++ b/packages/core/types/src/http/file/admin/responses.ts @@ -2,10 +2,16 @@ import { DeleteResponse } from "../../common" import { AdminFile } from "./entities" export interface AdminFileResponse { + /** + * The file's details. + */ file: AdminFile } export interface AdminFileListResponse { + /** + * The list of uploaded files. + */ files: AdminFile[] } diff --git a/packages/core/types/src/http/file/common.ts b/packages/core/types/src/http/file/common.ts index 0d87af9cb2..ec260d2bbe 100644 --- a/packages/core/types/src/http/file/common.ts +++ b/packages/core/types/src/http/file/common.ts @@ -1,10 +1,30 @@ export interface BaseFile { + /** + * The ID of the file in the configured File Module Provider. + * For example, when using the Local File Provider Module (default provider), + * the ID is the file's path relative to the `static` directory. + */ id: string + /** + * The URL of the file. + */ url: string } export type BaseUploadFile = | { - files: ({ name: string; content: string } | File)[] + /** + * The list of files to upload. + */ + files: ({ + /** + * The name of the file. + */ + name: string; + /** + * The content of the file. + */ + content: string + } | File)[] } | FileList diff --git a/packages/core/types/src/http/fulfillment-provider/admin/responses.ts b/packages/core/types/src/http/fulfillment-provider/admin/responses.ts index 979700e0e0..210f5c6c87 100644 --- a/packages/core/types/src/http/fulfillment-provider/admin/responses.ts +++ b/packages/core/types/src/http/fulfillment-provider/admin/responses.ts @@ -14,5 +14,8 @@ export interface AdminFulfillmentProviderListResponse export interface AdminFulfillmentProviderOptionsListResponse extends PaginatedResponse<{ + /** + * The list of fulfillment options. + */ fulfillment_options: AdminFulfillmentProviderOption[] }> {} diff --git a/packages/core/types/src/http/payment/admin/queries.ts b/packages/core/types/src/http/payment/admin/queries.ts index fd74c4f328..c11cef6d26 100644 --- a/packages/core/types/src/http/payment/admin/queries.ts +++ b/packages/core/types/src/http/payment/admin/queries.ts @@ -43,7 +43,13 @@ export interface AdminPaymentFilters extends FindParams, BasePaymentFilters { export interface RefundReasonFilters extends FindParams, BaseFilterable { + /** + * Filter by refund reason ID(s). + */ id?: string | string[] + /** + * Query or keywords to search the refund reason's searchable fields. + */ q?: string } diff --git a/packages/core/types/src/http/payment/admin/responses.ts b/packages/core/types/src/http/payment/admin/responses.ts index f3c2b09a05..09d2735791 100644 --- a/packages/core/types/src/http/payment/admin/responses.ts +++ b/packages/core/types/src/http/payment/admin/responses.ts @@ -48,6 +48,9 @@ export interface RefundReasonResponse { } export type RefundReasonsResponse = PaginatedResponse<{ + /** + * The list of refund reasons. + */ refund_reasons: AdminRefundReason[] }> diff --git a/packages/core/types/src/http/promotion/admin/entities.ts b/packages/core/types/src/http/promotion/admin/entities.ts index b1239014dd..0e5fc2d2e7 100644 --- a/packages/core/types/src/http/promotion/admin/entities.ts +++ b/packages/core/types/src/http/promotion/admin/entities.ts @@ -8,12 +8,32 @@ import { } from "../common" export interface AdminPromotion extends BasePromotion { + /** + * The promotion's application method. + */ application_method?: AdminApplicationMethod + /** + * The rules for the promotion. + */ rules?: AdminPromotionRule[] } export interface AdminApplicationMethod extends BaseApplicationMethod { + /** + * The associated promotion. + */ promotion?: AdminPromotion + /** + * The target rules that strict which cart items or shipping methods can + * the promotion be applied to. + */ target_rules?: AdminPromotionRule[] + /** + * The buy rules that specify the conditions for the promotion if its type is `buyget`. + * It specifies the buy X part of the buy X get Y promotion. + * + * For example, if the promotion is a "buy 2 get 1 free" promotion, the buy rules + * indicate what should be bought to get the promotion. + */ buy_rules?: AdminPromotionRule[] } export interface AdminPromotionRule extends BasePromotionRule {} diff --git a/packages/core/types/src/http/promotion/admin/payloads.ts b/packages/core/types/src/http/promotion/admin/payloads.ts index cdf79f744a..954d9b40ca 100644 --- a/packages/core/types/src/http/promotion/admin/payloads.ts +++ b/packages/core/types/src/http/promotion/admin/payloads.ts @@ -9,9 +9,29 @@ import { import { AdminCreateCampaign } from "../../campaign" export interface AdminCreatePromotionRule { + /** + * The operator used to check whether the buy rule applies on a cart. + * For example, `eq` means that the cart's value for the specified attribute + * must match the specified value. + */ operator: PromotionRuleOperatorValues + /** + * The description of the promotion rule. + */ description?: string | null + /** + * The attribute to compare against when checking whether a promotion can be applied on a cart. + * + * @example + * items.product_id + */ attribute: string + /** + * The value to compare against when checking whether a promotion can be applied on a cart. + * + * @example + * prod_123 + */ values: string | string[] } @@ -24,62 +44,198 @@ export interface AdminUpdatePromotionRule { } export interface AdminCreateApplicationMethod { + /** + * The description of the application method. + */ description?: string | null + /** + * The value of the application method. + */ value: number + /** + * The currency code of the application method. + * + * @example + * usd + */ currency_code?: string | null + /** + * The max quantity allowed in the cart for the associated promotion to be applied. + */ max_quantity?: number | null + /** + * The type of the application method. + */ type: ApplicationMethodTypeValues + /** + * The target type of the application method indicating whether the associated promotion is applied + * to the cart's items, shipping methods, or the whole order. + */ target_type: ApplicationMethodTargetTypeValues + /** + * The allocation value that indicates whether the associated promotion is applied on each + * item in a cart or split between the items in the cart. + */ allocation?: ApplicationMethodAllocationValues + /** + * The target rules of the application method. + */ target_rules?: AdminCreatePromotionRule[] + /** + * The buy rules of the application method. + */ buy_rules?: AdminCreatePromotionRule[] + /** + * The quantity of the application method. + */ apply_to_quantity?: number | null + /** + * The minimum quantity required for a `buyget` promotion to be applied. For example, + * if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is 2. + */ buy_rules_min_quantity?: number | null } export interface AdminUpdateApplicationMethod { + /** + * The description of the application method. + */ description?: string | null + /** + * The value of the application method. + */ value?: number + /** + * The max quantity allowed in the cart for the associated promotion to be applied. + */ max_quantity?: number | null + /** + * The currency code of the application method. + * + * @example + * usd + */ currency_code?: string | null + /** + * The type of the application method. + */ type?: ApplicationMethodTypeValues + /** + * The target type of the application method indicating whether the associated promotion is applied + * to the cart's items, shipping methods, or the whole order. + */ target_type?: ApplicationMethodTargetTypeValues + /** + * The allocation value that indicates whether the associated promotion is applied on each + * item in a cart or split between the items in the cart. + */ allocation?: ApplicationMethodAllocationValues + /** + * The target rules of the application method. + */ target_rules?: AdminCreatePromotionRule[] + /** + * The buy rules of the application method. + */ buy_rules?: AdminCreatePromotionRule[] + /** + * The quantity of the application method. + */ apply_to_quantity?: number | null + /** + * The minimum quantity required for a `buyget` promotion to be applied. For example, + * if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is 2. + */ buy_rules_min_quantity?: number | null } export interface AdminCreatePromotion { + /** + * The promotion's code. + */ code: string + /** + * Whether the promotion is applied automatically + * or requires the customer to manually apply it + * by entering the code at checkout. + */ is_automatic?: boolean + /** + * The type of promotion. + */ type: PromotionTypeValues + /** + * The ID of the campaign that the promotion belongs to. + */ campaign_id?: string | null + /** + * The campaign that the promotion belongs to. + */ campaign?: AdminCreateCampaign + /** + * The application method of the promotion. + */ application_method: AdminCreateApplicationMethod + /** + * The rules of the promotion. + */ rules?: AdminCreatePromotionRule[] } export interface AdminUpdatePromotion { + /** + * The promotion's code. + */ code?: string + /** + * Whether the promotion is applied automatically + * or requires the customer to manually apply it + * by entering the code at checkout. + */ is_automatic?: boolean + /** + * The type of promotion. + */ type?: PromotionTypeValues + /** + * The status of the promotion. + */ status?: PromotionStatusValues + /** + * The ID of the campaign that the promotion belongs to. + */ campaign_id?: string | null + /** + * The campaign that the promotion belongs to. + */ campaign?: AdminCreateCampaign + /** + * The application method of the promotion. + */ application_method?: AdminUpdateApplicationMethod + /** + * The rules of the promotion. + */ rules?: AdminCreatePromotionRule[] } export interface BatchAddPromotionRulesReq { + /** + * The rules to add. + */ rules: AdminCreatePromotionRule[] } export interface BatchRemovePromotionRulesReq { + /** + * The IDs of the rules to remove. + */ rule_ids: string[] } export interface BatchUpdatePromotionRulesReq { + /** + * The rules to update. + */ rules: AdminUpdatePromotionRule[] } diff --git a/packages/core/types/src/http/promotion/admin/queries.ts b/packages/core/types/src/http/promotion/admin/queries.ts index 9b75d37095..b2a849bca1 100644 --- a/packages/core/types/src/http/promotion/admin/queries.ts +++ b/packages/core/types/src/http/promotion/admin/queries.ts @@ -6,16 +6,54 @@ export interface AdminGetPromotionParams extends SelectParams {} export interface AdminGetPromotionsParams extends FindParams, BaseFilterable { + /** + * Search for a promotion by its searchable + */ q?: string + /** + * Filter by promotion code. + */ code?: string | string[] + /** + * Filter by campaign ID to retrieve promotions by campaign. + */ campaign_id?: string | string[] + /** + * Filter by the promotion's application method. + */ application_method?: { + /** + * Filter by the promotion's application method currency code. + */ currency_code?: string | string[] } + /** + * Filter by the promotion's currency code. + */ + currency_code?: string | string[] + /** + * Filter by the promotion's created date. + */ created_at?: OperatorMap + /** + * Filter by the promotion's updated date. + */ updated_at?: OperatorMap + /** + * Filter by the promotion's deleted date. + */ deleted_at?: OperatorMap + /** + * Filter by the promotion's application method type. + */ + application_method_type?: string | string[] + /** + * An array of filters to apply on the entity, where each item in the array is joined with an "and" condition. + */ $and?: AdminGetPromotionsParams[] + /** + * An array of filters to apply on the entity, where each item in the array is joined with an "or" condition. + */ $or?: AdminGetPromotionsParams[] } @@ -30,6 +68,12 @@ export interface AdminGetPromotionRuleTypeParams extends SelectParams { } export interface AdminGetPromotionsRuleValueParams extends FindParams { + /** + * Search for a rule value by its searchable + */ q?: string + /** + * Filter by rule value. + */ value?: string | string[] } diff --git a/packages/core/types/src/http/promotion/admin/responses.ts b/packages/core/types/src/http/promotion/admin/responses.ts index 7aed19c8b5..23a6c9d082 100644 --- a/packages/core/types/src/http/promotion/admin/responses.ts +++ b/packages/core/types/src/http/promotion/admin/responses.ts @@ -8,10 +8,16 @@ import { } from "./entities" export interface AdminPromotionResponse { + /** + * The promotion's details. + */ promotion: AdminPromotion } export type AdminPromotionListResponse = PaginatedResponse<{ + /** + * The list of promotions. + */ promotions: AdminPromotion[] }> @@ -20,6 +26,9 @@ export interface PromotionRuleResponse { } export type AdminPromotionRuleListResponse = { + /** + * The list of promotion rules. + */ rules: AdminPromotionRule[] } @@ -28,6 +37,9 @@ export interface RuleAttributeOptionsResponse { } export type AdminRuleAttributeOptionsListResponse = { + /** + * The list of rule attribute options. + */ attributes: AdminRuleAttributeOption[] } @@ -50,6 +62,9 @@ export interface RuleValueOptionsResponse { * @experimental */ export type AdminRuleValueOptionsListResponse = { + /** + * The list of rule value options. + */ values: AdminRuleValueOption[] } diff --git a/packages/core/types/src/http/promotion/common.ts b/packages/core/types/src/http/promotion/common.ts index 8b406960eb..6321269ae4 100644 --- a/packages/core/types/src/http/promotion/common.ts +++ b/packages/core/types/src/http/promotion/common.ts @@ -9,10 +9,36 @@ import { import { AdminCampaign } from "../campaign" export interface BasePromotionRule { + /** + * The rule's ID. + */ id: string + /** + * The rule's description. + */ description?: string | null + /** + * The attribute to compare against when checking whether a promotion can be applied on a cart. + * + * @example + * items.product_id + */ attribute?: string + /** + * The operator used to check whether the buy rule applies on a cart. + * For example, `eq` means that the cart's value for the specified attribute + * must match the specified value. + * + * @example + * eq + */ operator?: PromotionRuleOperatorValues + /** + * The values to compare against when checking whether a promotion can be applied on a cart. + * + * @example + * prod_123 + */ values: BasePromotionRuleValue[] } @@ -47,13 +73,28 @@ export interface BasePromotion { } export interface BasePromotionRuleValue { + /** + * The rule value's ID. + */ id: string + /** + * The rule value's value. + */ value?: string } export interface BaseRuleAttributeOptions { + /** + * The rule attribute option's ID. + */ id: string + /** + * The rule attribute option's value. + */ value: string + /** + * The rule attribute option's label. + */ label: string /** * @ignore @@ -71,12 +112,24 @@ export interface BaseRuleAttributeOptions { * @ignore */ hydrate?: boolean + /** + * The attribute option's operators. + */ operators: BaseRuleOperatorOptions[] } export interface BaseRuleOperatorOptions { + /** + * The operator option's ID. + */ id: string + /** + * The operator option's value. + */ value: string + /** + * The operator option's label. + */ label: string } diff --git a/packages/core/types/src/http/region/admin/entities.ts b/packages/core/types/src/http/region/admin/entities.ts index 7d3c377d1d..71ea3dad13 100644 --- a/packages/core/types/src/http/region/admin/entities.ts +++ b/packages/core/types/src/http/region/admin/entities.ts @@ -1,6 +1,9 @@ import { BaseRegion, BaseRegionCountry } from "../common" export interface AdminRegion extends Omit { + /** + * The countries in the region. + */ countries?: AdminRegionCountry[] } export interface AdminRegionCountry extends BaseRegionCountry {} diff --git a/packages/core/types/src/http/region/admin/payloads.ts b/packages/core/types/src/http/region/admin/payloads.ts index be353ae27c..4a589c06bd 100644 --- a/packages/core/types/src/http/region/admin/payloads.ts +++ b/packages/core/types/src/http/region/admin/payloads.ts @@ -1,19 +1,87 @@ export interface AdminCreateRegion { + /** + * The name of the region. + */ name: string + /** + * The currency code of the region. + * + * @example + * "usd" + */ currency_code: string + /** + * The 2 ISO code of the countries in the region. + * + * @example + * ["us", "ca"] + */ countries?: string[] + /** + * Whether taxes are automatically calculated during checkout + * for this region. + */ automatic_taxes?: boolean + /** + * Whether prices in this region include taxes by default. + * + * Learn more in the [tax-inclusive pricing](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing#content) documentation. + */ is_tax_inclusive?: boolean + /** + * The IDs of the payment providers that are available in this region. The IDs are + * of the format `pp_{identifier}_{id}`. + * + * @example + * ["pp_stripe_stripe", "pp_system_default"] + */ payment_providers?: string[] + /** + * Custom key-value pairs that can be added to the region. + */ metadata?: Record | null } export interface AdminUpdateRegion { + /** + * The name of the region. + */ name?: string + /** + * The currency code of the region. + * + * @example + * "usd" + */ currency_code?: string + /** + * The 2 ISO code of the countries in the region. + * + * @example + * ["us", "ca"] + */ countries?: string[] + /** + * Whether taxes are automatically calculated during checkout + * for this region. + */ automatic_taxes?: boolean + /** + * Whether prices in this region include taxes by default. + * + * Learn more in the [tax-inclusive pricing](https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing#content) documentation. + */ is_tax_inclusive?: boolean + /** + * The IDs of the payment providers that are available in this region. The IDs are + * of the format `pp_{identifier}_{id}`. + * + * @example + * ["pp_stripe_stripe", "pp_system_default"] + */ payment_providers?: string[] + /** + * Custom key-value pairs that can be added to the region. + */ metadata?: Record | null } diff --git a/packages/core/types/src/http/region/admin/queries.ts b/packages/core/types/src/http/region/admin/queries.ts index 67eed7aef1..2d5fa3d829 100644 --- a/packages/core/types/src/http/region/admin/queries.ts +++ b/packages/core/types/src/http/region/admin/queries.ts @@ -5,12 +5,33 @@ import { BaseRegionCountryFilters } from "../common" export interface AdminRegionFilters extends FindParams, BaseFilterable { + /** + * Query or keywords to search the region's searchable fields. + */ q?: string + /** + * Filter by region ID(s). + */ id?: string | string[] + /** + * Filter by currency code(s). + */ currency_code?: string | string[] + /** + * Filter by region name(s). + */ name?: string | string[] + /** + * Apply filters on the region's creation date. + */ created_at?: OperatorMap + /** + * Apply filters on the region's update date. + */ updated_at?: OperatorMap + /** + * Apply filters on the region's deletion date. + */ deleted_at?: OperatorMap } export interface AdminRegionCountryFilters extends BaseRegionCountryFilters {} diff --git a/packages/core/types/src/http/region/admin/responses.ts b/packages/core/types/src/http/region/admin/responses.ts index 5a1a924108..d7e90d3ebe 100644 --- a/packages/core/types/src/http/region/admin/responses.ts +++ b/packages/core/types/src/http/region/admin/responses.ts @@ -2,10 +2,16 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminRegion } from "./entities" export interface AdminRegionResponse { + /** + * The region's details. + */ region: AdminRegion } export type AdminRegionListResponse = PaginatedResponse<{ + /** + * The list of regions. + */ regions: AdminRegion[] }> diff --git a/packages/core/types/src/http/reservation/admin/entities.ts b/packages/core/types/src/http/reservation/admin/entities.ts index b93f1d6abd..bbb2ff094c 100644 --- a/packages/core/types/src/http/reservation/admin/entities.ts +++ b/packages/core/types/src/http/reservation/admin/entities.ts @@ -1,17 +1,56 @@ import { AdminInventoryItem } from "../../inventory" export interface AdminReservation { + /** + * The reservation's ID. + */ id: string + /** + * The ID of the line item that the reservation is for. + */ line_item_id: string | null + /** + * The ID of the location that the quantity is reserved from. + */ location_id: string + /** + * The quantity that is reserved. + */ quantity: number + /** + * The ID of the reservation in an external system. + */ external_id: string | null + /** + * The description of the reservation. + */ description: string | null + /** + * The ID of the inventory item that the reservation is for. + */ inventory_item_id: string + /** + * The inventory item that the reservation is for. + */ inventory_item?: AdminInventoryItem + /** + * Custom key-value pairs that can be added to the reservation. + */ metadata?: Record + /** + * The ID of the user that created the reservation. + */ created_by?: string | null + /** + * The date that the reservation was deleted. + */ deleted_at?: Date | string | null + /** + * The date that the reservation was created. + */ created_at?: Date | string + /** + * The date that the reservation was updated. + */ updated_at?: Date | string } diff --git a/packages/core/types/src/http/reservation/admin/payloads.ts b/packages/core/types/src/http/reservation/admin/payloads.ts index 404f18a691..9d8523d2fd 100644 --- a/packages/core/types/src/http/reservation/admin/payloads.ts +++ b/packages/core/types/src/http/reservation/admin/payloads.ts @@ -1,15 +1,47 @@ export interface AdminCreateReservation { + /** + * The ID of the line item to create the reservation for. + */ line_item_id?: string | null + /** + * The ID of the location that the quantity + * is reserved from. + */ location_id: string + /** + * The ID of the inventory item that the reservation is for. + */ inventory_item_id: string + /** + * The quantity of the inventory item that is reserved. + */ quantity: number + /** + * The description of the reservation. + */ description?: string | null + /** + * Custom key-value pairs that can be added to the reservation. + */ metadata?: Record | null } export interface AdminUpdateReservation { + /** + * The ID of the location that the quantity + * is reserved from. + */ location_id?: string + /** + * The quantity of the inventory item that is reserved. + */ quantity?: number + /** + * The description of the reservation. + */ description?: string | null + /** + * Custom key-value pairs that can be added to the reservation. + */ metadata?: Record | null } diff --git a/packages/core/types/src/http/reservation/admin/queries.ts b/packages/core/types/src/http/reservation/admin/queries.ts index 68f1185535..f4bf1748ea 100644 --- a/packages/core/types/src/http/reservation/admin/queries.ts +++ b/packages/core/types/src/http/reservation/admin/queries.ts @@ -2,15 +2,49 @@ import { OperatorMap } from "../../../dal" import { SelectParams } from "../../common" export interface AdminGetReservationsParams { + /** + * The maximum number of reservations to retrieve. + */ limit?: number + /** + * The number of reservations to skip. + */ offset?: number + /** + * Filter by the ID(s) of the location(s) to retrieve the + * reservations for. + */ location_id?: string | string[] + /** + * Filter by the ID(s) of the inventory item(s) to retrieve the + * reservations for. + */ inventory_item_id?: string | string[] + /** + * Filter by the ID(s) of the line item(s) to retrieve the + * reservations for. + */ line_item_id?: string | string[] + /** + * Filter by the ID(s) of the user(s) to retrieve the + * reservations they created. + */ created_by?: string | string[] + /** + * Filter by reservation description(s). + */ description?: string | OperatorMap + /** + * Apply filters on the reservation's creation date. + */ created_at?: OperatorMap + /** + * Apply filters on the reservation's update date. + */ updated_at?: OperatorMap + /** + * Apply filters on the reservation's deletion date. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/reservation/admin/responses.ts b/packages/core/types/src/http/reservation/admin/responses.ts index 95b2cce141..2976e9a81a 100644 --- a/packages/core/types/src/http/reservation/admin/responses.ts +++ b/packages/core/types/src/http/reservation/admin/responses.ts @@ -2,10 +2,16 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminReservation } from "./entities" export interface AdminReservationResponse { + /** + * The reservation's details. + */ reservation: AdminReservation } export type AdminReservationListResponse = PaginatedResponse<{ + /** + * The list of reservations. + */ reservations: AdminReservation[] }> diff --git a/packages/core/types/src/http/return-reason/admin/payloads.ts b/packages/core/types/src/http/return-reason/admin/payloads.ts index 8475f2d320..af1417972d 100644 --- a/packages/core/types/src/http/return-reason/admin/payloads.ts +++ b/packages/core/types/src/http/return-reason/admin/payloads.ts @@ -1,11 +1,32 @@ type AdminBaseReturnReasonPayload = { + /** + * The return reason's value. + * + * @example + * "refund" + */ value: string + /** + * The return reason's label. + * + * @example + * "Refund" + */ label: string + /** + * The return reason's description. + */ description?: string + /** + * Custom key-value pairs that can be added to the return reason. + */ metadata?: Record | null } export interface AdminCreateReturnReason extends AdminBaseReturnReasonPayload { + /** + * The ID of the return reason's parent. + */ parent_return_reason_id?: string } diff --git a/packages/core/types/src/http/return-reason/admin/queries.ts b/packages/core/types/src/http/return-reason/admin/queries.ts index d7683017b8..d8ee222ed4 100644 --- a/packages/core/types/src/http/return-reason/admin/queries.ts +++ b/packages/core/types/src/http/return-reason/admin/queries.ts @@ -5,6 +5,9 @@ import { BaseReturnReasonListParams } from "../common" export interface AdminReturnReasonListParams extends BaseReturnReasonListParams, BaseFilterable { + /** + * Apply filters on the return reason's deletion date. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/return-reason/admin/responses.ts b/packages/core/types/src/http/return-reason/admin/responses.ts index a5196499ce..a09e099659 100644 --- a/packages/core/types/src/http/return-reason/admin/responses.ts +++ b/packages/core/types/src/http/return-reason/admin/responses.ts @@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminReturnReason } from "../admin" export interface AdminReturnReasonResponse { + /** + * The return reason's details. + */ return_reason: AdminReturnReason } export interface AdminReturnReasonListResponse extends PaginatedResponse<{ + /** + * The list of return reasons. + */ return_reasons: AdminReturnReason[] }> {} diff --git a/packages/core/types/src/http/return-reason/common.ts b/packages/core/types/src/http/return-reason/common.ts index 5d4e253de2..1745132d7b 100644 --- a/packages/core/types/src/http/return-reason/common.ts +++ b/packages/core/types/src/http/return-reason/common.ts @@ -2,12 +2,39 @@ import { OperatorMap } from "../../dal" import { FindParams } from "../common" export interface BaseReturnReason { + /** + * The return reason's ID. + */ id: string + /** + * The return reason's value. + * + * @example + * "refund" + */ value: string + /** + * The return reason's label. + * + * @example + * "Refund" + */ label: string + /** + * The return reason's description. + */ description?: string | null + /** + * Custom key-value pairs that can be added to the return reason. + */ metadata?: Record | null + /** + * The date that the return reason was created. + */ created_at: string + /** + * The date that the return reason was updated. + */ updated_at: string } diff --git a/packages/core/types/src/http/return/admin/entities.ts b/packages/core/types/src/http/return/admin/entities.ts index ef57aecda7..26469e2a83 100644 --- a/packages/core/types/src/http/return/admin/entities.ts +++ b/packages/core/types/src/http/return/admin/entities.ts @@ -2,5 +2,8 @@ import { BaseReturn, BaseReturnItem } from "../common" export interface AdminReturnItem extends BaseReturnItem {} export interface AdminReturn extends BaseReturn { + /** + * The return's items. + */ items: AdminReturnItem[] } diff --git a/packages/core/types/src/http/return/admin/payloads.ts b/packages/core/types/src/http/return/admin/payloads.ts index 3c50bd72b5..1e099bc727 100644 --- a/packages/core/types/src/http/return/admin/payloads.ts +++ b/packages/core/types/src/http/return/admin/payloads.ts @@ -1,17 +1,53 @@ export interface AdminInitiateReturnRequest { + /** + * The ID of the order that the return belongs to. + */ order_id: string + /** + * The ID of the stock location to return the items to. + */ location_id?: string + /** + * The return's description. + */ description?: string + /** + * A note that is viewed by admins only to + * describe the return. + */ internal_note?: string + /** + * Whether to send a notification to the customer + * for return updates. + */ no_notification?: boolean + /** + * Custom key-value pairs that can be added to the return. + */ metadata?: Record } export interface AdminAddReturnItem { + /** + * The ID of the order item to add to the return. + */ id: string + /** + * The quantity of the item to return. + */ quantity: number + /** + * A note to describe why the item is being returned. + */ description?: string + /** + * A note that is viewed by admins only to + * describe why the item is being returned. + */ internal_note?: string + /** + * Custom key-value pairs that can be added to the return item. + */ metadata?: Record } @@ -20,63 +56,189 @@ export interface AdminAddReturnItems { } export interface AdminUpdateReturnItems { + /** + * The quantity of the item to return. + */ quantity?: number + /** + * A note that is viewed by admins only to + * describe why the item is being returned. + */ internal_note?: string | null + /** + * The ID of the return reason to associate with the item. + */ reason_id?: string | null } export interface AdminAddReturnShipping { + /** + * The ID of the shipping option that the shipping method + * is created from. + */ shipping_option_id: string + /** + * A custom amount to set for the shipping method. + * If not provided, the shipping option's fixed or calculated amount will be used. + */ custom_amount?: number + /** + * A note to describe the shipping method. + */ description?: string + /** + * A note that is viewed by admins only to + * describe the shipping method. + */ internal_note?: string + /** + * Custom key-value pairs that can be added to the shipping method. + */ metadata?: Record } export interface AdminUpdateReturnShipping { + /** + * A custom amount to set for the shipping method. + * If not provided, the shipping option's fixed or calculated amount will be used. + */ custom_amount?: number + /** + * A note that is viewed by admins only to + * describe the shipping method. + */ internal_note?: string + /** + * Custom key-value pairs that can be added to the shipping method. + */ metadata?: Record } export interface AdminConfirmReturnRequest { + /** + * Whether to send a notification to the customer + * for return updates. + */ no_notification?: boolean } export interface AdminUpdateReturnRequest { + /** + * The ID of the stock location to return the items to. + */ location_id?: string | null + /** + * Whether to send a notification to the customer + * for return updates. + */ no_notification?: boolean + /** + * Custom key-value pairs that can be added to the return. + */ metadata?: Record | null } export interface AdminConfirmReceiveReturn { + /** + * Whether to send a notification to the customer + * for return updates. + */ no_notification?: boolean } export interface AdminInitiateReceiveReturn { + /** + * A note that is viewed by admins only to + * describe the return. + */ internal_note?: string + /** + * A note to describe the return. + */ description?: string + /** + * Custom key-value pairs that can be added to the return. + */ metadata?: Record } export interface AdminReceiveItems { - items: { id: string; quantity: number; internal_note?: string }[] + /** + * The received items in the return. + */ + items: { + /** + * The ID of the received item. + */ + id: string; + /** + * The received quantity of the item. + */ + quantity: number; + /** + * A note that is viewed by admins only to + * describe the received item. + */ + internal_note?: string + }[] } export interface AdminDismissItems { - items: { id: string; quantity: number; internal_note?: string }[] + /** + * The damaged items to add to the return. + */ + items: { + /** + * The ID of the item to add to the return. + */ + id: string; + /** + * The quantity of the item that is damaged. + */ + quantity: number; + /** + * A note that is viewed by admins only to + * describe the damaged item. + */ + internal_note?: string + }[] } export interface AdminUpdateReceiveItems { + /** + * The received quantity of the item. + */ quantity?: number + /** + * A note that is viewed by admins only to + * describe the received item. + */ internal_note?: string + /** + * The ID of the return reason to associate with the item. + */ reason_id?: string + /** + * Custom key-value pairs that can be added to the received item. + */ metadata?: Record } export interface AdminUpdateDismissItems { + /** + * The quantity of the item that is damaged. + */ quantity?: number + /** + * A note that is viewed by admins only to + */ internal_note?: string + /** + * The ID of the return reason to associate with the item. + */ reason_id?: string + /** + * Custom key-value pairs that can be added to the received item. + */ metadata?: Record } diff --git a/packages/core/types/src/http/return/admin/queries.ts b/packages/core/types/src/http/return/admin/queries.ts index 539ed58c0b..559193e04c 100644 --- a/packages/core/types/src/http/return/admin/queries.ts +++ b/packages/core/types/src/http/return/admin/queries.ts @@ -2,13 +2,28 @@ import { OperatorMap } from "../../../dal" import { FindParams } from "../../common" export interface AdminReturnFilters extends FindParams { + /** + * Filter by return ID(s). + */ id?: string[] | string | OperatorMap + /** + * Filter by order ID(s) to retrieve their returns. + */ order_id?: string[] | string | OperatorMap + /** + * Filter by status. + */ status?: | string[] | string | Record | OperatorMap> + /** + * Filter by the date when the return was created. + */ created_at?: OperatorMap + /** + * Filter by the date when the return was updated. + */ updated_at?: OperatorMap } diff --git a/packages/core/types/src/http/return/admin/responses.ts b/packages/core/types/src/http/return/admin/responses.ts index f3b3c368b8..96ad90091b 100644 --- a/packages/core/types/src/http/return/admin/responses.ts +++ b/packages/core/types/src/http/return/admin/responses.ts @@ -4,10 +4,16 @@ import { AdminOrderPreview } from "../../order" import { AdminReturn } from "./entities" export interface AdminReturnResponse { + /** + * The return's details. + */ return: AdminReturn } export type AdminReturnsResponse = PaginatedResponse<{ + /** + * The list of returns. + */ returns: AdminReturn[] }> diff --git a/packages/core/types/src/http/return/common.ts b/packages/core/types/src/http/return/common.ts index f196fdee97..e2a5abc3f8 100644 --- a/packages/core/types/src/http/return/common.ts +++ b/packages/core/types/src/http/return/common.ts @@ -1,30 +1,103 @@ import { ReturnStatus } from "../../order" export interface BaseReturnItem { + /** + * The return item's ID. + */ id: string + /** + * The quantity of the item that is to be returned. + */ quantity: number + /** + * The quantity of the item that has been received. + */ received_quantity: number + /** + * The quantity of the item that has been received and is damaged. + * This quantity is not added back to the quantity in the stock location. + */ damaged_quantity: number + /** + * The ID of the associated return reason. + */ reason_id?: string + /** + * A note to describe why the item is being returned. + */ note?: string + /** + * The ID of the order item that is being returned. + */ item_id: string + /** + * The ID of the return that the item belongs to. + */ return_id: string + /** + * Custom key-value pairs that can be added to the return item. + */ metadata?: Record } export interface BaseReturn { + /** + * The return's ID. + */ id: string + /** + * The ID of the order that the return belongs to. + */ order_id: string + /** + * The return's status. + */ status?: ReturnStatus + /** + * The ID of the exchange that the return belongs to, + * if available. + */ exchange_id?: string + /** + * The ID of the stock location that the items are returned to. + */ location_id?: string + /** + * The ID of the claim that the return belongs to, + * if available. + */ claim_id?: string + /** + * The order's version once the return is applied. + */ order_version: number + /** + * The display ID of the return. + */ display_id: number + /** + * Whether to send the customers notifications about + * return updates. + */ no_notification?: boolean + /** + * The amount that is to be refunded to the customer. + */ refund_amount?: number + /** + * The return's items. + */ items: BaseReturnItem[] + /** + * The date when the return was received. + */ received_at: string + /** + * The date when the return was created. + */ created_at: string + /** + * The date when the return was canceled. + */ canceled_at: string } diff --git a/packages/core/types/src/http/sales-channel/admin/entities.ts b/packages/core/types/src/http/sales-channel/admin/entities.ts index e06cce6213..72e274deee 100644 --- a/packages/core/types/src/http/sales-channel/admin/entities.ts +++ b/packages/core/types/src/http/sales-channel/admin/entities.ts @@ -1,10 +1,34 @@ export interface AdminSalesChannel { + /** + * The sales channel's ID. + */ id: string + /** + * The sales channel's name. + */ name: string + /** + * The sales channel's description. + */ description: string | null + /** + * Whether the sales channel is disabled. + */ is_disabled: boolean + /** + * Custom key-value pairs that can be added to the sales channel. + */ metadata: Record | null + /** + * The sales channel's creation date. + */ created_at: string + /** + * The sales channel's last updated date. + */ updated_at: string + /** + * The sales channel's deletion date. + */ deleted_at: string | null } diff --git a/packages/core/types/src/http/sales-channel/admin/payloads.ts b/packages/core/types/src/http/sales-channel/admin/payloads.ts index e6c0ce1509..29c0d98ef1 100644 --- a/packages/core/types/src/http/sales-channel/admin/payloads.ts +++ b/packages/core/types/src/http/sales-channel/admin/payloads.ts @@ -1,18 +1,50 @@ export interface AdminCreateSalesChannel { + /** + * The sales channel's name. + */ name: string + /** + * The sales channel's description. + */ description?: string + /** + * Whether the sales channel is disabled. + * + * @defaultValue `false` + */ is_disabled?: boolean + /** + * Custom key-value pairs that can be added to the sales channel. + */ metadata?: Record } export interface AdminUpdateSalesChannel { + /** + * The sales channel's name. + */ name?: string + /** + * The sales channel's description. + */ description?: string | null + /** + * Whether the sales channel is disabled. + */ is_disabled?: boolean + /** + * Custom key-value pairs that can be added to the sales channel. + */ metadata?: Record } export interface AdminUpdateSalesChannelProducts { + /** + * The IDs of the products to add to the sales channel. + */ add?: string[] + /** + * The IDs of the products to remove from the sales channel. + */ remove?: string[] } diff --git a/packages/core/types/src/http/sales-channel/admin/queries.ts b/packages/core/types/src/http/sales-channel/admin/queries.ts index cba41e4faf..c14d0d0b15 100644 --- a/packages/core/types/src/http/sales-channel/admin/queries.ts +++ b/packages/core/types/src/http/sales-channel/admin/queries.ts @@ -4,14 +4,46 @@ import { FindParams } from "../../common" export interface AdminSalesChannelListParams extends FindParams, BaseFilterable { + /** + * Filter by sales channel ID(s). + */ id?: string | string[] + /** + * Query or keywords to search the sales channel's searchable fields. + */ q?: string + /** + * Filter by sales channel name. + */ name?: string | string[] + /** + * Filter by sales channel description. + */ description?: string + /** + * Filter by whether the sales channel is disabled. + */ is_disabled?: boolean + /** + * Filter by the ID(s) of the location(s) to retrieve the + * sales channels for. + */ location_id?: string | string[] + /** + * Filter by the ID(s) of the publishable key(s) to retrieve the + * sales channels for. + */ publishable_key_id?: string | string[] + /** + * Filter by the date when the sales channel was created. + */ created_at?: OperatorMap + /** + * Filter by the date when the sales channel was updated. + */ updated_at?: OperatorMap + /** + * Filter by the date when the sales channel was deleted. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/sales-channel/admin/responses.ts b/packages/core/types/src/http/sales-channel/admin/responses.ts index 15e26611ae..c40c06e5c3 100644 --- a/packages/core/types/src/http/sales-channel/admin/responses.ts +++ b/packages/core/types/src/http/sales-channel/admin/responses.ts @@ -2,10 +2,16 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminSalesChannel } from "./entities" export interface AdminSalesChannelResponse { + /** + * The sales channel's details. + */ sales_channel: AdminSalesChannel } export type AdminSalesChannelListResponse = PaginatedResponse<{ + /** + * The list of sales channels. + */ sales_channels: AdminSalesChannel[] }> diff --git a/packages/core/types/src/http/shipping-option/admin/entities.ts b/packages/core/types/src/http/shipping-option/admin/entities.ts index cab9ad9429..f83b7428d6 100644 --- a/packages/core/types/src/http/shipping-option/admin/entities.ts +++ b/packages/core/types/src/http/shipping-option/admin/entities.ts @@ -6,62 +6,248 @@ import { AdminPrice } from "../../pricing" import { AdminShippingProfile } from "../../shipping-profile" export interface AdminShippingOptionType { + /** + * The ID of the shipping option type. + */ id: string + /** + * The label of the shipping option type. + */ label: string + /** + * The description of the shipping option type. + */ description: string + /** + * The code of the shipping option type. + */ code: string + /** + * The ID of the shipping option that this type is created for. + */ shipping_option_id: string + /** + * The date when the shipping option type was created. + */ created_at: string + /** + * The date when the shipping option type was updated. + */ updated_at: string + /** + * The date when the shipping option type was deleted. + */ deleted_at: string | null } export interface AdminShippingOptionRule { + /** + * The ID of the shipping option rule. + */ id: string + /** + * The attribute of the shipping option rule. + * + * @example + * "enabled_in_store" + */ attribute: string + /** + * The operator of the shipping option rule. + * + * @example + * "eq" + */ operator: RuleOperatorType + /** + * The value of the shipping option rule. + * + * @example + * "true" + */ value: string | string[] | null + /** + * The ID of the shipping option that this rule is created for. + */ shipping_option_id: string + /** + * The date when the shipping option rule was created. + */ created_at: string + /** + * The date when the shipping option rule was updated. + */ updated_at: string + /** + * The date when the shipping option rule was deleted. + */ deleted_at: string | null } -// TODO: This type is complete, but it's not clear what the `rules` field is supposed to return in all cases. +/** + * @privateRemarks + * + * TODO: This type is complete, but it's not clear what the `rules` field is supposed to return in all cases. + */ export interface AdminShippingOptionPriceRule { + /** + * The ID of the shipping option price rule. + */ id: string + /** + * The value of the shipping option price rule. + * + * @example + * "region_123" + */ value: string | number + /** + * The operator of the shipping option price rule. + * + * @example + * "eq" + */ operator: RuleOperatorType + /** + * The attribute of the shipping option price rule. + * + * @example + * "region_id" + */ attribute: string + /** + * The ID of the shipping option price that this rule is created for. + */ price_id: string + /** + * The priority of the shipping option price rule. + */ priority: number + /** + * The date when the shipping option price rule was created. + */ created_at: string + /** + * The date when the shipping option price rule was updated. + */ updated_at: string + /** + * The date when the shipping option price rule was deleted. + */ deleted_at: string | null } export interface AdminShippingOptionPrice extends AdminPrice { + /** + * The rules of the shipping option price. + */ price_rules: AdminShippingOptionPriceRule[] + /** + * The number of rules of the shipping option price. + */ rules_count: number } export interface AdminShippingOption { + /** + * The shipping option's ID. + */ id: string + /** + * The shipping option's name. Customers can + * see this name during checkout. + * + * @example + * "Standard Shipping" + */ name: string + /** + * The type of shipping option's price. + */ price_type: ShippingOptionPriceType + /** + * The ID of the service zone that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#service-zone-restrictions) + * documentation. + */ service_zone_id: string + /** + * The service zone that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#service-zone-restrictions) + * documentation. + */ service_zone: AdminServiceZone + /** + * The ID of the fulfillment provider that the shipping option belongs to. + */ provider_id: string + /** + * The fulfillment provider that the shipping option belongs to. + */ provider: AdminFulfillmentProvider + /** + * The ID of the shipping option's type. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ shipping_option_type_id: string | null + /** + * The shipping option's type. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ type: AdminShippingOptionType + /** + * The ID of the shipping profile that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ shipping_profile_id: string + /** + * The shipping profile that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ shipping_profile: AdminShippingProfile + /** + * The rules of the shipping option. + * + * Learn more in the [Shipping Option Rules](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-option-rules) + * documentation. + */ rules: AdminShippingOptionRule[] + /** + * The prices of the shipping option. + */ prices: AdminShippingOptionPrice[] + /** + * Additional data that is useful for third-party fulfillment providers + * that process fulfillments for the shipping option. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property) + * documentation. + */ data: Record | null + /** + * Custom key-value pairs that can be added to the shipping option. + */ metadata: Record | null + /** + * The date when the shipping option was created. + */ created_at: Date + /** + * The date when the shipping option was updated. + */ updated_at: Date + /** + * The date when the shipping option was deleted. + */ deleted_at: Date | null } diff --git a/packages/core/types/src/http/shipping-option/admin/payloads.ts b/packages/core/types/src/http/shipping-option/admin/payloads.ts index 514226f795..028a214d18 100644 --- a/packages/core/types/src/http/shipping-option/admin/payloads.ts +++ b/packages/core/types/src/http/shipping-option/admin/payloads.ts @@ -2,89 +2,270 @@ import { RuleOperatorType } from "../../../common" import { ShippingOptionPriceType } from "../../../fulfillment" export interface AdminCreateShippingOptionRule { + /** + * The operator of the shipping option rule. + */ operator: RuleOperatorType + /** + * The attribute of the shipping option rule. + * + * @example + * `enabled_in_store` + */ attribute: string + /** + * The value of the shipping option rule. + * + * @example + * `true` + */ value: string | string[] } export interface AdminCreateShippingOptionType { + /** + * The label of the shipping option type. + */ label: string + /** + * The description of the shipping option type. + */ description: string + /** + * The code of the shipping option type. + */ code: string } interface AdminShippingOptionPriceRulePayload { + /** + * The operator of the shipping option price rule. + * + * @example + * "eq" + */ operator: string + /** + * The attribute of the shipping option price rule. + * + * @example + * "region_id" + */ attribute: string + /** + * The value of the shipping option price rule. + * + * @example + * "region_123" + */ value: string | string[] | number } interface AdminShippingOptionPriceWithRules { + /** + * The rules of the shipping option price that + * indicate when the price should be applied. + */ rules?: AdminShippingOptionPriceRulePayload[] } export interface AdminCreateShippingOptionPriceWithCurrency extends AdminShippingOptionPriceWithRules { + /** + * The currency code of the shipping option price. + * + * @example + * "usd" + */ currency_code: string + /** + * The amount of the shipping option price. + */ amount: number } export interface AdminCreateShippingOptionPriceWithRegion extends AdminShippingOptionPriceWithRules { + /** + * The ID of the region that the shipping option price belongs to. + */ region_id: string + /** + * The amount of the shipping option price. + */ amount: number } export interface AdminCreateShippingOption { + /** + * The name of the shipping option. Customers can + * view this name during checkout. + * + * @example + * "Standard Shipping" + */ name: string + /** + * The ID of the service zone that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#service-zone-restrictions) + * documentation. + */ service_zone_id: string + /** + * The ID of the shipping profile that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ shipping_profile_id: string + /** + * Additional data that is useful for third-party fulfillment providers + * that process fulfillments for the shipping option. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property) + * documentation. + */ data?: Record + /** + * The type of shipping option's price. + */ price_type: ShippingOptionPriceType + /** + * The ID of the fulfillment provider that the shipping option belongs to. + */ provider_id: string + /** + * The type of shipping option. + * + * Learn more in the [Shipping Option](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ type: AdminCreateShippingOptionType + /** + * The prices of the shipping option. + */ prices: ( | AdminCreateShippingOptionPriceWithCurrency | AdminCreateShippingOptionPriceWithRegion )[] + /** + * The rules of the shipping option. + * + * Learn more in the [Shipping Option Rules](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-option-rules) + * documentation. + */ rules?: AdminCreateShippingOptionRule[] } export interface AdminUpdateShippingOptionRule extends AdminCreateShippingOptionRule { + /** + * The ID of the shipping option rule that is being updated. + */ id: string } export interface AdminUpdateShippingOptionPriceWithCurrency extends AdminShippingOptionPriceWithRules { + /** + * The ID of the shipping option price that is being updated. + * If not provided, a new shipping option price will be created. + */ id?: string + /** + * The currency code of the shipping option price. + * + * @example + * "usd" + */ currency_code?: string + /** + * The amount of the shipping option price. + */ amount?: number } export interface AdminUpdateShippingOptionPriceWithRegion extends AdminShippingOptionPriceWithRules { + /** + * The ID of the shipping option price that is being updated. + * If not provided, a new shipping option price will be created. + */ id?: string + /** + * The ID of the region that the shipping option price belongs to. + */ region_id?: string + /** + * The amount of the shipping option price. + */ amount?: number } export interface AdminUpdateShippingOption { + /** + * The name of the shipping option. Customers can + * view this name during checkout. + * + * @example + * "Standard Shipping" + */ name?: string + /** + * Additional data that is useful for third-party fulfillment providers + * that process fulfillments for the shipping option. + */ data?: Record + /** + * The type of shipping option's price. + */ price_type?: ShippingOptionPriceType + /** + * The ID of the fulfillment provider that the shipping option belongs to. + */ provider_id?: string + /** + * The ID of the shipping profile that the shipping option belongs to. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ shipping_profile_id?: string + /** + * The type of shipping option. + * + * Learn more in the [Shipping Options](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-profile-and-types) + * documentation. + */ type?: AdminCreateShippingOptionType + /** + * The prices of the shipping option. + */ prices?: ( | AdminUpdateShippingOptionPriceWithCurrency | AdminUpdateShippingOptionPriceWithRegion )[] + /** + * The rules of the shipping option. + * + * Learn more in the [Shipping Option Rules](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#shipping-option-rules) + * documentation. + */ rules?: (AdminUpdateShippingOptionRule | AdminCreateShippingOptionRule)[] } export interface AdminUpdateShippingOptionRules { + /** + * The rules to create. + */ create?: any[] + /** + * The rules to update. + */ update?: any[] + /** + * The rules to delete. + */ delete?: string[] } diff --git a/packages/core/types/src/http/shipping-option/admin/queries.ts b/packages/core/types/src/http/shipping-option/admin/queries.ts index e66b60e581..eb4d4a39fc 100644 --- a/packages/core/types/src/http/shipping-option/admin/queries.ts +++ b/packages/core/types/src/http/shipping-option/admin/queries.ts @@ -2,16 +2,52 @@ import { OperatorMap } from "../../../dal" import { FindParams } from "../../common" export interface AdminShippingOptionListParams extends FindParams { + /** + * Filter by shipping option ID(s), + */ id?: string | string[] + /** + * Query or keywords to search the shipping option's searchable fields. + */ q?: string + /** + * Filter by the ID of the service zone(s) to retrieve the shipping options for. + */ service_zone_id?: string | string[] + /** + * Filter by the ID of the stock location(s) to retrieve the shipping options for. + */ stock_location_id?: string | string[] + /** + * Filter by whether the shipping option is a return shipping option. + */ is_return?: boolean + /** + * Filter by whether the shipping option is only available to admins. + */ admin_only?: boolean + /** + * Filter by the ID of the shipping profile(s) to retrieve the shipping options for. + */ shipping_profile_id?: string | string[] + /** + * Filter by the ID of the provider(s) to retrieve the shipping options for. + */ provider_id?: string | string[] + /** + * Filter by the ID of the shipping option type(s) to retrieve the shipping options for. + */ shipping_option_type_id?: string | string[] + /** + * Filter by the date the shipping option was created. + */ created_at?: OperatorMap + /** + * Filter by the date the shipping option was updated. + */ updated_at?: OperatorMap + /** + * Filter by the date the shipping option was deleted. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/shipping-option/admin/responses.ts b/packages/core/types/src/http/shipping-option/admin/responses.ts index 4f0908367f..081b6ae8e4 100644 --- a/packages/core/types/src/http/shipping-option/admin/responses.ts +++ b/packages/core/types/src/http/shipping-option/admin/responses.ts @@ -2,10 +2,16 @@ import { BatchResponse, DeleteResponse, PaginatedResponse } from "../../common" import { AdminShippingOption, AdminShippingOptionRule } from "./entities" export interface AdminShippingOptionResponse { + /** + * The shipping option's details. + */ shipping_option: AdminShippingOption } export type AdminShippingOptionListResponse = PaginatedResponse<{ + /** + * The list of shipping options. + */ shipping_options: AdminShippingOption[] }> diff --git a/packages/core/types/src/http/shipping-option/store/payloads.ts b/packages/core/types/src/http/shipping-option/store/payloads.ts index 8d604852d3..33c5fcadca 100644 --- a/packages/core/types/src/http/shipping-option/store/payloads.ts +++ b/packages/core/types/src/http/shipping-option/store/payloads.ts @@ -1,4 +1,16 @@ +/** + * The details of the price calculation. + */ export type StoreCalculateShippingOptionPrice = { + /** + * The ID of the cart to calculate the price for. + */ cart_id: string + /** + * Additional data passed to the shipping option's fulfillment provider. This is useful + * if the third-party fulfillment provider requires additional data to calculate the price. + * + * Learn more in the [Shipping Option documentation](https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option#data-property). + */ data?: Record } 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 8e64fc2ea9..b27380ab6b 100644 --- a/packages/core/types/src/http/shipping-option/store/responses.ts +++ b/packages/core/types/src/http/shipping-option/store/responses.ts @@ -1,9 +1,21 @@ import { StoreCartShippingOption } from "../../fulfillment" +/** + * The response of listing the shipping options for a cart. + */ export interface StoreShippingOptionListResponse { + /** + * The shipping options for the cart. + */ shipping_options: StoreCartShippingOption[] } +/** + * The response of calculating the price of a shipping option. + */ export interface StoreShippingOptionResponse { + /** + * The shipping option's details. + */ shipping_option: StoreCartShippingOption } diff --git a/packages/core/types/src/http/shipping-profile/admin/entities.ts b/packages/core/types/src/http/shipping-profile/admin/entities.ts index 78e0cad09f..0199e77ff5 100644 --- a/packages/core/types/src/http/shipping-profile/admin/entities.ts +++ b/packages/core/types/src/http/shipping-profile/admin/entities.ts @@ -1,9 +1,30 @@ export interface AdminShippingProfile { + /** + * The ID of the shipping profile. + */ id: string + /** + * The name of the shipping profile. + */ name: string + /** + * The type of the shipping profile. + */ type: string + /** + * Custom key-value pairs that can be added to the shipping profile. + */ metadata: Record | null + /** + * The date when the shipping profile was created. + */ created_at: string + /** + * The date when the shipping profile was updated. + */ updated_at: string + /** + * The date when the shipping profile was deleted. + */ deleted_at: string | null } diff --git a/packages/core/types/src/http/shipping-profile/admin/payloads.ts b/packages/core/types/src/http/shipping-profile/admin/payloads.ts index 1e7a05e2d0..41460b3db2 100644 --- a/packages/core/types/src/http/shipping-profile/admin/payloads.ts +++ b/packages/core/types/src/http/shipping-profile/admin/payloads.ts @@ -1,11 +1,29 @@ export interface AdminCreateShippingProfile { + /** + * The name of the shipping profile. + */ name: string + /** + * The type of the shipping profile. + */ type: string + /** + * Custom key-value pairs that can be added to the shipping profile. + */ metadata?: Record } export interface AdminUpdateShippingProfile { + /** + * The name of the shipping profile. + */ name?: string + /** + * The type of the shipping profile. + */ type?: string + /** + * Custom key-value pairs that can be added to the shipping profile. + */ metadata?: Record | null } diff --git a/packages/core/types/src/http/shipping-profile/admin/queries.ts b/packages/core/types/src/http/shipping-profile/admin/queries.ts index b9e93673d5..f60065d856 100644 --- a/packages/core/types/src/http/shipping-profile/admin/queries.ts +++ b/packages/core/types/src/http/shipping-profile/admin/queries.ts @@ -2,13 +2,40 @@ import { OperatorMap } from "../../../dal" import { FindParams } from "../../common" export interface AdminShippingProfileListParams extends FindParams { + /** + * Filter by shipping profile ID(s). + */ id?: string | string[] + /** + * Query or keywords to search the shipping profile's searchable fields. + */ q?: string + /** + * Filter by shipping profile type. + */ type?: string + /** + * Filter by shipping profile name. + */ name?: string + /** + * Filter by the date the shipping profile was created. + */ created_at?: OperatorMap + /** + * Filter by the date the shipping profile was updated. + */ updated_at?: OperatorMap + /** + * Filter by the date the shipping profile was deleted. + */ deleted_at?: OperatorMap + /** + * An array of filters to apply on the entity, where each item in the array is joined with an "and" condition. + */ $and?: AdminShippingProfileListParams[] + /** + * An array of filters to apply on the entity, where each item in the array is joined with an "or" condition. + */ $or?: AdminShippingProfileListParams[] } diff --git a/packages/core/types/src/http/shipping-profile/admin/responses.ts b/packages/core/types/src/http/shipping-profile/admin/responses.ts index 480091e34f..93593201b6 100644 --- a/packages/core/types/src/http/shipping-profile/admin/responses.ts +++ b/packages/core/types/src/http/shipping-profile/admin/responses.ts @@ -2,10 +2,16 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminShippingProfile } from "./entities" export interface AdminShippingProfileResponse { + /** + * The shipping profile's details. + */ shipping_profile: AdminShippingProfile } export type AdminShippingProfileListResponse = PaginatedResponse<{ + /** + * The list of shipping profiles. + */ shipping_profiles: AdminShippingProfile[] }> diff --git a/packages/core/types/src/http/stock-locations/admin/entities.ts b/packages/core/types/src/http/stock-locations/admin/entities.ts index 872aad37a1..2f4acc3fc1 100644 --- a/packages/core/types/src/http/stock-locations/admin/entities.ts +++ b/packages/core/types/src/http/stock-locations/admin/entities.ts @@ -15,11 +15,32 @@ export interface AdminStockLocationAddress { } export interface AdminStockLocation { + /** + * The ID of the stock location. + */ id: string + /** + * The name of the stock location. + */ name: string + /** + * The ID of the address associated with the stock location. + */ address_id: string + /** + * The address associated with the stock location. + */ address?: AdminStockLocationAddress + /** + * The sales channels associated with the stock location. + */ sales_channels?: AdminSalesChannel[] + /** + * The fulfillment providers associated with the stock location. + */ fulfillment_providers?: AdminFulfillmentProvider[] + /** + * The fulfillment sets associated with the stock location. + */ fulfillment_sets?: AdminFulfillmentSet[] } diff --git a/packages/core/types/src/http/stock-locations/admin/payloads.ts b/packages/core/types/src/http/stock-locations/admin/payloads.ts index 2bcbc72d4b..71d4388f09 100644 --- a/packages/core/types/src/http/stock-locations/admin/payloads.ts +++ b/packages/core/types/src/http/stock-locations/admin/payloads.ts @@ -1,34 +1,103 @@ interface AdminUpsertStockLocationAddress { + /** + * The first line of the address. + */ address_1: string + /** + * The second line of the address. + */ address_2?: string + /** + * The company name associated with the address. + */ company?: string + /** + * The country code of the address. + * + * @example + * "us" + */ country_code: string + /** + * The city of the address. + */ city?: string + /** + * The phone number of the address. + */ phone?: string + /** + * The postal or zip code of the address. + */ postal_code?: string + /** + * The province or state of the address. + */ province?: string } export interface AdminCreateStockLocation { + /** + * The name of the stock location. + */ name: string + /** + * The ID of the address to associate with the stock location. + * If you provide an `address`, you don't need to provide this property. + */ address_id?: string + /** + * The address to create or update for the stock location. + * If you provide an `address_id`, you don't need + * to provide this property. + */ address?: AdminUpsertStockLocationAddress + /** + * Custom key-value pairs that can be added to the stock location. + */ metadata?: Record } export interface AdminUpdateStockLocation { + /** + * The name of the stock location. + */ name?: string + /** + * The ID of the address to associate with the stock location. + * If you provide an `address`, you don't need to provide this property. + */ address_id?: string + /** + * The address to create or update for the stock location. + * If you provide an `address_id`, you don't need + * to provide this property. + */ address?: AdminUpsertStockLocationAddress + /** + * Custom key-value pairs that can be added to the stock location. + */ metadata?: Record } export interface AdminUpdateStockLocationSalesChannels { + /** + * The IDs of the sales channels to add to the stock location. + */ add?: string[] + /** + * The IDs of the sales channels to remove from the stock location. + */ remove?: string[] } export interface AdminCreateStockLocationFulfillmentSet { + /** + * The name of the fulfillment set. + */ name: string + /** + * The type of the fulfillment set. + */ type: string } diff --git a/packages/core/types/src/http/stock-locations/admin/queries.ts b/packages/core/types/src/http/stock-locations/admin/queries.ts index e49c1cfbe7..a5b5cf55ee 100644 --- a/packages/core/types/src/http/stock-locations/admin/queries.ts +++ b/packages/core/types/src/http/stock-locations/admin/queries.ts @@ -4,14 +4,36 @@ import { FindParams } from "../../common" export interface AdminStockLocationListParams extends FindParams, BaseFilterable { + /** + * Filter by stock location ID(s). + */ id?: string | string[] + /** + * Query or keywords to search the stock location's searchable fields. + */ q?: string + /** + * Filter by stock location name. + */ name?: string | string[] + /** + * Filter by stock location address ID(s). + */ address_id?: string | string[] + /** + * Filter by sales channel ID(s) to retrieve the stock locations for. + */ sales_channel_id?: string | string[] - $and?: AdminStockLocationListParams[] - $or?: AdminStockLocationListParams[] + /** + * Filter by the date the stock location was created. + */ created_at?: OperatorMap + /** + * Filter by the date the stock location was updated. + */ updated_at?: OperatorMap + /** + * Filter by the date the stock location was deleted. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/stock-locations/admin/responses.ts b/packages/core/types/src/http/stock-locations/admin/responses.ts index 89fcc40be7..7127d2d2d8 100644 --- a/packages/core/types/src/http/stock-locations/admin/responses.ts +++ b/packages/core/types/src/http/stock-locations/admin/responses.ts @@ -2,11 +2,17 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminStockLocation } from "./entities" export interface AdminStockLocationResponse { + /** + * The stock location's details. + */ stock_location: AdminStockLocation } export interface AdminStockLocationListResponse extends PaginatedResponse<{ + /** + * The list of stock locations. + */ stock_locations: AdminStockLocation[] }> {} diff --git a/packages/core/types/src/http/store/admin/entities.ts b/packages/core/types/src/http/store/admin/entities.ts index cbeaf01d4d..f7086737d7 100644 --- a/packages/core/types/src/http/store/admin/entities.ts +++ b/packages/core/types/src/http/store/admin/entities.ts @@ -1,24 +1,78 @@ import { AdminCurrency } from "../../currency" export interface AdminStoreCurrency { + /** + * The currency's ID. + */ id: string + /** + * The currency code. + * + * @example + * "usd" + */ currency_code: string + /** + * The ID of the store that the currency belongs to. + */ store_id: string + /** + * Whether the currency is the default currency for the store. + */ is_default: boolean + /** + * The currency's details. + */ currency: AdminCurrency + /** + * The date the currency was created. + */ created_at: string + /** + * The date the currency was updated. + */ updated_at: string + /** + * The date the currency was deleted. + */ deleted_at: string | null } export interface AdminStore { + /** + * The store's ID. + */ id: string + /** + * The store's name. + */ name: string + /** + * The store's supported currencies. + */ supported_currencies: AdminStoreCurrency[] + /** + * The store's default sales channel ID. + */ default_sales_channel_id: string | null + /** + * The store's default region ID. + */ default_region_id: string | null + /** + * The store's default location ID. + */ default_location_id: string | null + /** + * Custom key-value pairs that can be added to the store. + */ metadata: Record | null + /** + * The date the store was created. + */ created_at: string + /** + * The date the store was updated. + */ updated_at: string } diff --git a/packages/core/types/src/http/store/admin/queries.ts b/packages/core/types/src/http/store/admin/queries.ts index 632c48fb02..e9d51d2583 100644 --- a/packages/core/types/src/http/store/admin/queries.ts +++ b/packages/core/types/src/http/store/admin/queries.ts @@ -4,8 +4,17 @@ import { FindParams, SelectParams } from "../../common" export interface AdminStoreListParams extends BaseFilterable, FindParams { + /** + * Query or keywords to search the store's searchable fields. + */ q?: string + /** + * Filter by store ID(s). + */ id?: string | string[] + /** + * Filter by store name. + */ name?: string | string[] } diff --git a/packages/core/types/src/http/store/admin/responses.ts b/packages/core/types/src/http/store/admin/responses.ts index d15d7bbb54..669cb7ba34 100644 --- a/packages/core/types/src/http/store/admin/responses.ts +++ b/packages/core/types/src/http/store/admin/responses.ts @@ -2,10 +2,16 @@ import { PaginatedResponse } from "../../common" import { AdminStore } from "./entities" export interface AdminStoreResponse { + /** + * The store's details. + */ store: AdminStore } export interface AdminStoreListResponse extends PaginatedResponse<{ + /** + * The list of stores. + */ stores: AdminStore[] }> {} diff --git a/packages/core/types/src/http/tax-rate/admin/entities.ts b/packages/core/types/src/http/tax-rate/admin/entities.ts index cab2ad1477..4182915676 100644 --- a/packages/core/types/src/http/tax-rate/admin/entities.ts +++ b/packages/core/types/src/http/tax-rate/admin/entities.ts @@ -1,23 +1,77 @@ import { AdminTaxRegion } from "../../tax-region" export interface AdminTaxRateRule { + /** + * The name of the table that the rule references. + * + * @example + * "product_type" + */ reference: string + /** + * The ID of the record in the table that the rule references. + * + * @example + * "protyp_123" + */ reference_id: string } export interface AdminTaxRate { + /** + * The tax rate's ID. + */ id: string + /** + * The tax rate's percentage rate. + */ rate: number | null + /** + * The tax rate's code. + */ code: string + /** + * The tax rate's name. + */ name: string + /** + * Custom key-value pairs that can be added to the tax rate. + */ metadata: Record | null + /** + * The ID of the tax region associated with the tax rate. + */ tax_region_id: string + /** + * Whether the tax rate is combinable with other tax rates. + */ is_combinable: boolean + /** + * Whether the tax rate is the default tax rate in its tax region. + */ is_default: boolean + /** + * The date the tax rate was created. + */ created_at: string + /** + * The date the tax rate was updated. + */ updated_at: string + /** + * The date the tax rate was deleted. + */ deleted_at: null + /** + * The ID of the user who created the tax rate. + */ created_by: string | null + /** + * The tax region associated with the tax rate. + */ tax_region: AdminTaxRegion + /** + * The rules associated with the tax rate. + */ rules: AdminTaxRateRule[] } diff --git a/packages/core/types/src/http/tax-rate/admin/payloads.ts b/packages/core/types/src/http/tax-rate/admin/payloads.ts index 65e69b2214..447d5d1480 100644 --- a/packages/core/types/src/http/tax-rate/admin/payloads.ts +++ b/packages/core/types/src/http/tax-rate/admin/payloads.ts @@ -1,25 +1,82 @@ interface AdminCreateTaxRateRule { + /** + * The name of the table that the rule references. + * + * @example + * "product_type" + */ reference: string + /** + * The ID of the record in the table that the rule references. + * + * @example + * "protyp_123" + */ reference_id: string } export interface AdminCreateTaxRate { + /** + * The name of the tax rate. + */ name: string + /** + * The ID of the tax region associated with the tax rate. + */ tax_region_id: string + /** + * The rate of the tax rate. + */ rate?: number + /** + * The code of the tax rate. + */ code: string + /** + * The rules of the tax rate. + */ rules?: AdminCreateTaxRateRule[] + /** + * Whether the tax rate is the default tax rate in its tax region. + */ is_default?: boolean + /** + * Whether the tax rate is combinable with other tax rates. + */ is_combinable?: boolean + /** + * Custom key-value pairs that can be added to the tax rate. + */ metadata?: Record } export interface AdminUpdateTaxRate { + /** + * The name of the tax rate. + */ name?: string + /** + * The percentage rate of the tax rate. + */ rate?: number + /** + * The code of the tax rate. + */ code: string + /** + * The rules of the tax rate. + */ rules?: AdminCreateTaxRateRule[] + /** + * Whether the tax rate is the default tax rate in its tax region. + */ is_default?: boolean + /** + * Whether the tax rate is combinable with other tax rates. + */ is_combinable?: boolean + /** + * Custom key-value pairs that can be added to the tax rate. + */ metadata?: Record } diff --git a/packages/core/types/src/http/tax-rate/admin/queries.ts b/packages/core/types/src/http/tax-rate/admin/queries.ts index f3ee81e1d5..a556751dfd 100644 --- a/packages/core/types/src/http/tax-rate/admin/queries.ts +++ b/packages/core/types/src/http/tax-rate/admin/queries.ts @@ -4,14 +4,44 @@ import { FindParams } from "../../common" export interface AdminTaxRateListParams extends FindParams, BaseFilterable { + /** + * Query or keywords to search the tax rate's searchable fields. + */ q?: string + /** + * Filter by tax region ID(s). + */ tax_region_id?: string | string[] | OperatorMap + /** + * Filter by whether the tax rate is the default tax rate in its tax region. + */ is_default?: "true" | "false" + /** + * Filter by service zone ID(s) to retrieve tax rates that are associated with the service zones. + */ service_zone_id?: string + /** + * Filter by shipping profile ID(s) to retrieve tax rates that are associated with the shipping profiles. + */ shipping_profile_id?: string + /** + * Filter by tax provider ID(s) to retrieve tax rates that are associated with the providers. + */ provider_id?: string + /** + * Filter by shipping option type ID(s) to retrieve tax rates that are associated with the shipping option types. + */ shipping_option_type_id?: string + /** + * Filter by the date the tax rate was created. + */ created_at?: OperatorMap + /** + * Filter by the date the tax rate was updated. + */ updated_at?: OperatorMap + /** + * Filter by the date the tax rate was deleted. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/tax-rate/admin/responses.ts b/packages/core/types/src/http/tax-rate/admin/responses.ts index ae603652c9..2dec04b6f7 100644 --- a/packages/core/types/src/http/tax-rate/admin/responses.ts +++ b/packages/core/types/src/http/tax-rate/admin/responses.ts @@ -6,10 +6,16 @@ import { import { AdminTaxRate } from "./entities" export interface AdminTaxRateResponse { + /** + * The tax rate's details. + */ tax_rate: AdminTaxRate } export type AdminTaxRateListResponse = PaginatedResponse<{ + /** + * The list of tax rates. + */ tax_rates: AdminTaxRate[] }> diff --git a/packages/core/types/src/http/tax-region/admin/entities.ts b/packages/core/types/src/http/tax-region/admin/entities.ts index 05a87a2ce6..3d5cab7afc 100644 --- a/packages/core/types/src/http/tax-region/admin/entities.ts +++ b/packages/core/types/src/http/tax-region/admin/entities.ts @@ -1,16 +1,58 @@ import { AdminTaxRate } from "../../tax-rate" export interface AdminTaxRegion { + /** + * The tax region's ID. + */ id: string + /** + * The tax region's country code. + * + * @example + * "us" + */ country_code: string | null + /** + * The tax region's province or state code. + * + * @example + * "ca" + */ province_code: string | null + /** + * Custom key-value pairs that can be added to the tax region. + */ metadata: Record | null + /** + * The ID of the parent tax region. + */ parent_id: string | null + /** + * The date the tax region was created. + */ created_at: string + /** + * The date the tax region was updated. + */ updated_at: string + /** + * The date the tax region was deleted. + */ deleted_at: string | null + /** + * The ID of the user who created the tax region. + */ created_by: string | null + /** + * The tax rates associated with the tax region. + */ tax_rates: AdminTaxRate[] + /** + * The parent tax region. + */ parent: AdminTaxRegion | null + /** + * The child tax regions. + */ children: AdminTaxRegion[] } diff --git a/packages/core/types/src/http/tax-region/admin/payloads.ts b/packages/core/types/src/http/tax-region/admin/payloads.ts index 125a6545a7..cee80806f6 100644 --- a/packages/core/types/src/http/tax-region/admin/payloads.ts +++ b/packages/core/types/src/http/tax-region/admin/payloads.ts @@ -1,13 +1,43 @@ export interface AdminCreateTaxRegion { + /** + * The country code of the tax region. + */ country_code: string + /** + * The province code of the tax region. + */ province_code?: string + /** + * The ID of the parent tax region. + */ parent_id?: string + /** + * The default tax rate of the tax region. + */ default_tax_rate?: { + /** + * The percentage rate of the default tax rate. + */ rate?: number + /** + * The code of the default tax rate. + */ code: string + /** + * The name of the default tax rate. + */ name: string + /** + * Whether the default tax rate is combinable with other tax rates. + */ is_combinable?: boolean + /** + * Custom key-value pairs that can be added to the default tax rate. + */ metadata?: Record } + /** + * Custom key-value pairs that can be added to the tax region. + */ metadata?: Record } diff --git a/packages/core/types/src/http/tax-region/admin/queries.ts b/packages/core/types/src/http/tax-region/admin/queries.ts index 891b4bdac6..0f88155779 100644 --- a/packages/core/types/src/http/tax-region/admin/queries.ts +++ b/packages/core/types/src/http/tax-region/admin/queries.ts @@ -4,14 +4,42 @@ import { FindParams, SelectParams } from "../../common" export interface AdminTaxRegionListParams extends FindParams, BaseFilterable { + /** + * Filter by tax region ID(s). + */ id?: string | string[] + /** + * Query or keywords to search the tax region's searchable fields. + */ q?: string + /** + * Filter by the tax region's parent ID(s) to retrieve its children. + */ parent_id?: string | string[] | OperatorMap + /** + * Filter by the tax region's country code(s). + */ country_code?: string | string[] | OperatorMap + /** + * Filter by the tax region's province code(s). + */ province_code?: string | string[] | OperatorMap + /** + * Filter by the date the tax region was created. + */ created_at?: string | OperatorMap + /** + * Filter by the date the tax region was updated. + */ updated_at?: string | OperatorMap + /** + * Filter by the date the tax region was deleted. + */ deleted_at?: string | OperatorMap + /** + * Filter by the ID of the user who created the tax region to + * retrieve tax regions created by a specific user. + */ created_by?: string | OperatorMap } diff --git a/packages/core/types/src/http/tax-region/admin/responses.ts b/packages/core/types/src/http/tax-region/admin/responses.ts index bc83add8da..5ee33dfdeb 100644 --- a/packages/core/types/src/http/tax-region/admin/responses.ts +++ b/packages/core/types/src/http/tax-region/admin/responses.ts @@ -2,10 +2,16 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminTaxRegion } from "./entities" export interface AdminTaxRegionResponse { + /** + * The tax region's details. + */ tax_region: AdminTaxRegion } export type AdminTaxRegionListResponse = PaginatedResponse<{ + /** + * The list of tax regions. + */ tax_regions: AdminTaxRegion[] }> diff --git a/packages/core/types/src/http/user/admin/entities.ts b/packages/core/types/src/http/user/admin/entities.ts index 1bdead260f..d6de435a51 100644 --- a/packages/core/types/src/http/user/admin/entities.ts +++ b/packages/core/types/src/http/user/admin/entities.ts @@ -1,11 +1,38 @@ export interface AdminUser { + /** + * The user's ID. + */ id: string + /** + * The user's email. + */ email: string + /** + * The user's first name. + */ first_name: string | null + /** + * The user's last name. + */ last_name: string | null + /** + * The URL of the user's avatar image. + */ avatar_url: string | null + /** + * Custom key-value pairs that can be added to the user. + */ metadata: Record | null + /** + * The date the user was created. + */ created_at: string + /** + * The date the user was updated. + */ updated_at: string + /** + * The date the user was deleted. + */ deleted_at: string | null } diff --git a/packages/core/types/src/http/user/admin/payloads.ts b/packages/core/types/src/http/user/admin/payloads.ts index a40f739683..f54b62abe5 100644 --- a/packages/core/types/src/http/user/admin/payloads.ts +++ b/packages/core/types/src/http/user/admin/payloads.ts @@ -6,8 +6,20 @@ export interface AdminCreateUser { } export interface AdminUpdateUser { + /** + * The first name of the user. + */ first_name?: string | null + /** + * The last name of the user. + */ last_name?: string | null + /** + * The URL of the user's avatar image. + */ avatar_url?: string | null + /** + * Custom key-value pairs that can be added to the user. + */ metadata?: Record | null } diff --git a/packages/core/types/src/http/user/admin/queries.ts b/packages/core/types/src/http/user/admin/queries.ts index c3de9d97e5..e202dea0ec 100644 --- a/packages/core/types/src/http/user/admin/queries.ts +++ b/packages/core/types/src/http/user/admin/queries.ts @@ -2,13 +2,37 @@ import { OperatorMap } from "../../../dal" import { FindParams, SelectParams } from "../../common" export interface AdminUserListParams extends FindParams { + /** + * Query or keywords to search the user's searchable fields. + */ q?: string + /** + * Filter by user ID(s). + */ id?: string | string[] + /** + * Filter by email(s). + */ email?: string | null + /** + * Filter by first name(s). + */ first_name?: string | null + /** + * Filter by last name(s). + */ last_name?: string | null + /** + * Filter by the date the user was created. + */ created_at?: OperatorMap + /** + * Filter by the date the user was updated. + */ updated_at?: OperatorMap + /** + * Filter by the date the user was deleted. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/user/admin/responses.ts b/packages/core/types/src/http/user/admin/responses.ts index 9433397ec8..92c5224abd 100644 --- a/packages/core/types/src/http/user/admin/responses.ts +++ b/packages/core/types/src/http/user/admin/responses.ts @@ -2,10 +2,18 @@ import { DeleteResponse, PaginatedResponse } from "../../common" import { AdminUser } from "./entities" export interface AdminUserResponse { + /** + * The user's details. + */ user: AdminUser } export interface AdminUserListResponse - extends PaginatedResponse<{ users: AdminUser[] }> {} + extends PaginatedResponse<{ + /** + * The list of users. + */ + users: AdminUser[] + }> {} export interface AdminUserDeleteResponse extends DeleteResponse<"user"> {} diff --git a/packages/core/types/src/http/workflow-execution/admin/entities.ts b/packages/core/types/src/http/workflow-execution/admin/entities.ts index 21d6bef2e6..22e1150b1b 100644 --- a/packages/core/types/src/http/workflow-execution/admin/entities.ts +++ b/packages/core/types/src/http/workflow-execution/admin/entities.ts @@ -27,66 +27,201 @@ export type TransactionStepState = | "timeout" interface AdminWorkflowExecutionExecution { + /** + * The details of the workflow execution's steps. + * The key is the step's ID, and the value is the step's details. + */ steps: Record } export type StepInvokeResult = { + /** + * The output details of the step. + */ output: { + /** + * The output of the step. This is the first parameter + * passed to the returned `StepResponse` function. + */ output: unknown + /** + * The input of the step's compensation function. + * This is the second parameter passed to the returned `StepResponse` function. + */ compensateInput: unknown } } export type StepError = { + /** + * The error details. + */ error: Record + /** + * The ID of the action that failed. + */ action: string + /** + * The type of the handler that failed. It can be `invoke` or `compensate`. + */ handlerType: string } export interface WorkflowExecutionContext { + /** + * The data of the workflow execution. + */ data: { + /** + * The details of the invocation of the workflow execution's steps. + * The key is the step's ID, and the value is the step's details. + * + * These details are only included for steps that have their `saveResponse` property set to `true`. + */ invoke: Record + /** + * The payload or input of the workflow execution. + */ payload?: unknown } + /** + * The output of the compensation function of the workflow execution. + * The key is the step's ID, and the value is the compensation function's output. + * + * These details are only included for steps that have their `saveResponse` property set to `true`. + */ compensate: Record + /** + * The errors of the workflow execution. + */ errors: StepError[] } export interface WorkflowExecutionDefinition { + /** + * If true, the step is executed asynchronously. This means that the workflow will not wait for the response of this step. + * Async steps require to have their responses set using `setStepSuccess` or `setStepFailure`, unless it is combined with `backgroundExecution: true`. + * If combined with a timeout, and any response is not set within that interval, the step will be marked as `TransactionStepStatus.TIMEOUT` and the workflow will be reverted immediately. + */ async?: boolean + /** + * If true, the compensation function for this step is executed asynchronously. Which means, the response has to be set using `setStepSuccess` or `setStepFailure`. + */ compensateAsync?: boolean + /** + * If true, no compensation action will be triggered for this step in case of a failure. + */ noCompensation?: boolean + /** + * Indicates whether the workflow should continue even if there is a permanent failure in this step. + * In case it is set to true, the children steps of this step will not be executed and their status will be marked as `TransactionStepState`.SKIPPED_FAILURE. + */ continueOnPermanentFailure?: boolean + /** + * The maximum number of times this step should be retried in case of temporary failures. + * The default is 0 (no retries). + */ maxRetries?: number + /** + * If true, the workflow will not wait for their sibling steps to complete before moving to the next step. + */ noWait?: boolean + /** + * The interval (in seconds) between retry attempts after a temporary failure. + * The default is to retry immediately. + */ retryInterval?: number + /** + * The interval (in seconds) to retry a step even if its status is `TransactionStepStatus.WAITING`. + */ retryIntervalAwaiting?: number + /** + * If true, the response of this step will be stored. + * Default is true. + */ saveResponse?: boolean + /** + * The maximum amount of time (in seconds) to wait for this step to complete. + * This is NOT an execution timeout, the step will always be executed and wait for its response. + * If the response is not received within the timeout set, it will be marked as `TransactionStepStatus.TIMEOUT` and the workflow will be reverted as soon as it receives the response. + */ timeout?: number } export interface WorkflowExecutionFn { + /** + * The state of the step. + */ state: TransactionStepState + /** + * The status of the step. + */ status: TransactionStepStatus } export interface AdminWorkflowExecutionStep { + /** + * The ID of the step. + */ id: string + /** + * The invoke function of the step. + */ invoke: WorkflowExecutionFn + /** + * The definition of the step. + */ definition: WorkflowExecutionDefinition + /** + * The compensate function of the step. + */ compensate: WorkflowExecutionFn + /** + * The depth of the step. + */ depth: number + /** + * The date the step was started. + */ startedAt: number } export interface AdminWorkflowExecution { + /** + * The ID of the workflow execution. + */ id: string + /** + * The ID of the workflow. + */ workflow_id: string + /** + * The ID of the transaction. + */ transaction_id: string + /** + * The execution details of the workflow. + */ execution: AdminWorkflowExecutionExecution + /** + * The context of the workflow execution. + * This includes the data, errors and the output of the step and compensation functions of the workflow execution. + */ context: WorkflowExecutionContext + /** + * The state of the workflow execution. + */ state: TransactionState + /** + * The date the workflow execution was created. + */ created_at: Date + /** + * The date the workflow execution was updated. + */ updated_at: Date + /** + * The date the workflow execution was deleted. + */ deleted_at?: Date | null } diff --git a/packages/core/types/src/http/workflow-execution/admin/queries.ts b/packages/core/types/src/http/workflow-execution/admin/queries.ts index b8aa1b511e..58aa1009e4 100644 --- a/packages/core/types/src/http/workflow-execution/admin/queries.ts +++ b/packages/core/types/src/http/workflow-execution/admin/queries.ts @@ -1,6 +1,12 @@ import { FindParams } from "../../common" export interface AdminGetWorkflowExecutionsParams extends FindParams { + /** + * Filter by the ID of the transaction to retrieve workflow executions for a specific transaction. + */ transaction_id?: string | string[] + /** + * Filter by the ID of the workflow to retrieve workflow executions for a specific workflow. + */ workflow_id?: string | string[] } diff --git a/packages/core/types/src/http/workflow-execution/admin/responses.ts b/packages/core/types/src/http/workflow-execution/admin/responses.ts index 41552d9a7f..9057274443 100644 --- a/packages/core/types/src/http/workflow-execution/admin/responses.ts +++ b/packages/core/types/src/http/workflow-execution/admin/responses.ts @@ -3,10 +3,16 @@ import { PaginatedResponse } from "../../common/response" import { AdminWorkflowExecution } from "./entities" export interface AdminWorkflowExecutionResponse { + /** + * The workflow execution's details. + */ workflow_execution: AdminWorkflowExecution } export type AdminWorkflowExecutionListResponse = PaginatedResponse<{ + /** + * The list of workflow executions. + */ workflow_executions: AdminWorkflowExecution[] }>