From 5ea3100c1029109b3725acc327ef44a6a2314f11 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 22 Oct 2024 14:19:04 +0300 Subject: [PATCH] chore(js-sdk,types): add tsdocs for admin JS SDK methods [1/n] (#9667) Add TSDocs to admin JS SDK from API keys to currencies [1/n] --- packages/core/js-sdk/src/admin/api-key.ts | 147 ++++- packages/core/js-sdk/src/admin/campaign.ts | 135 +++++ packages/core/js-sdk/src/admin/claim.ts | 561 +++++++++++++++++- packages/core/js-sdk/src/admin/currency.ts | 83 ++- .../types/src/http/api-key/admin/payloads.ts | 9 + .../types/src/http/api-key/admin/queries.ts | 29 +- .../types/src/http/api-key/admin/responses.ts | 43 ++ .../types/src/http/campaign/admin/payloads.ts | 74 +++ .../src/http/campaign/admin/responses.ts | 51 ++ .../types/src/http/claim/admin/entities.ts | 9 + .../types/src/http/claim/admin/payloads.ts | 71 +++ .../types/src/http/claim/admin/queries.ts | 4 +- .../types/src/http/claim/admin/responses.ts | 24 + packages/core/types/src/http/claim/common.ts | 81 +++ .../core/types/src/http/common/request.ts | 6 + .../types/src/http/currency/admin/queries.ts | 6 + .../src/http/currency/admin/responses.ts | 10 +- .../core/types/src/http/currency/common.ts | 36 ++ .../types/src/http/order/admin/entities.ts | 33 ++ 19 files changed, 1383 insertions(+), 29 deletions(-) diff --git a/packages/core/js-sdk/src/admin/api-key.ts b/packages/core/js-sdk/src/admin/api-key.ts index 478743c5b5..e9e6d67073 100644 --- a/packages/core/js-sdk/src/admin/api-key.ts +++ b/packages/core/js-sdk/src/admin/api-key.ts @@ -1,4 +1,4 @@ -import { HttpTypes, PaginatedResponse } from "@medusajs/types" +import { HttpTypes } from "@medusajs/types" import { Client } from "../client" import { ClientHeaders } from "../types" @@ -14,18 +14,82 @@ export class ApiKey { this.client = client } + /** + * This methods retrieves a paginated list of API keys. It sends a request to the + * [List API Keys](https://docs.medusajs.com/v2/api/admin#api-keys_getapikeys) API route. + * + * @param queryParams - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of API keys. + * + * @example + * To retrieve the list of API keys: + * + * ```ts + * sdk.admin.apiKey.list() + * .then(({ api_keys, count, limit, offset }) => { + * console.log(api_keys) + * }) + * ``` + * + * 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.apiKey.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ api_keys, count, limit, offset }) => { + * console.log(api_keys) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each API key: + * + * ```ts + * sdk.admin.apiKey.list({ + * fields: "id,*sales_channels" + * }) + * .then(({ api_keys, count, limit, offset }) => { + * console.log(api_keys) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async list( queryParams?: HttpTypes.AdminGetApiKeysParams, headers?: ClientHeaders ) { return await this.client.fetch< - PaginatedResponse + HttpTypes.AdminApiKeyListResponse >(`/admin/api-keys`, { query: queryParams, headers, }) } + /** + * This method creates an API key. It sends a request to the [Create API Key](https://docs.medusajs.com/v2/api/admin#api-keys_postapikeys) + * API route. + * + * @param body - The API key's details. + * @param query - Configure the fields to retrieve in the created API key. + * @param headers - Headers to pass in the request + * @returns The created API key + * + * @example + * sdk.admin.apiKey.create({ + * title: "Development", + * type: "publishable" + * }) + * .then(({ api_key }) => { + * console.log(api_key) + * }) + */ async create( body: HttpTypes.AdminCreateApiKey, query?: HttpTypes.AdminGetApiKeysParams, @@ -42,6 +106,20 @@ export class ApiKey { ) } + /** + * This method revokes an API key. It sends a request to the + * [Revoke API Key](https://docs.medusajs.com/v2/api/admin#api-keys_postapikeysidrevoke) API route. + * + * @param id - The API key's ID. + * @param headers - Headers to pass in the request. + * @returns The API key's details. + * + * @example + * sdk.admin.apiKey.revoke("apk_123") + * .then(({ api_key }) => { + * console.log(api_key) + * }) + */ async revoke(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/api-keys/${id}/revoke`, @@ -52,6 +130,20 @@ export class ApiKey { ) } + /** + * This method retrieves an API key's details. It sends a request to the + * [Get API key](https://docs.medusajs.com/v2/api/admin#api-keys_getapikeysid) API route. + * + * @param id - The API key's ID. + * @param headers - Headers to pass in the request. + * @returns The API key's details. + * + * @example + * sdk.admin.apiKey.retrieve("apk_123") + * .then(({ api_key }) => { + * console.log(api_key) + * }) + */ async retrieve(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/api-keys/${id}`, @@ -61,6 +153,24 @@ export class ApiKey { ) } + /** + * This method updates an API key's details. It sends a request to the + * [Update API Key](https://docs.medusajs.com/v2/api/admin#api-keys_postapikeysid) API route. + * + * @param id - The API key's ID. + * @param body - The data to update in the API key. + * @param query - Configure the fields to retrieve in the API key. + * @param headers - Headers to pass in the request. + * @returns The API key's details. + * + * @example + * sdk.admin.apiKey.update("apk_123", { + * title: "Development" + * }) + * .then(({ api_key }) => { + * console.log(api_key) + * }) + */ async update( id: string, body: HttpTypes.AdminUpdateApiKey, @@ -78,6 +188,20 @@ export class ApiKey { ) } + /** + * This method deletes an API key by its ID. It sends a request to the + * [Delete API Key](https://docs.medusajs.com/v2/api/admin#api-keys_deleteapikeysid) API route. + * + * @param id - The API key's ID. + * @param headers - Headers to pass in the request. + * @returns The deletion's details. + * + * @example + * sdk.admin.apiKey.delete("apk_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch( `/admin/api-keys/${id}`, @@ -88,6 +212,25 @@ export class ApiKey { ) } + /** + * This method manages the sales channels associated with a publishable API key to either add + * or remove associations. It sends a request to the [Manage Sales Channels](https://docs.medusajs.com/v2/api/admin#api-keys_postapikeysidsaleschannels) + * API route. + * + * @param id - The API key's ID. + * @param body - The sales channels to add or remove from the API key. + * @param headers - Headers to pass in the request. + * @returns The API key's details. + * + * @example + * sdk.admin.apiKey.batchSalesChannels("apk_123", { + * add: ["sc_123"], + * remove: ["sc_321"] + * }) + * .then(({ api_key }) => { + * console.log(api_key) + * }) + */ async batchSalesChannels( id: string, body: HttpTypes.AdminBatchLink, diff --git a/packages/core/js-sdk/src/admin/campaign.ts b/packages/core/js-sdk/src/admin/campaign.ts index 6e53be4111..2e3599e7b8 100644 --- a/packages/core/js-sdk/src/admin/campaign.ts +++ b/packages/core/js-sdk/src/admin/campaign.ts @@ -14,6 +14,38 @@ export class Campaign { this.client = client } + /** + * This method retrieves a campaign by its ID. It sends a request to the + * [Get Campaign](https://docs.medusajs.com/v2/api/admin#campaigns_getcampaignsid) API route. + * + * @param id - The campaign's ID. + * @param query - Configure the fields to retrieve in the campaign. + * @param headers - Headers to pass in the request + * @returns The campaign's details. + * + * @example + * To retrieve a campaign by its ID: + * + * ```ts + * sdk.admin.campaign.retrieve("procamp_123") + * .then(({ campaign }) => { + * console.log(campaign) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.campaign.retrieve("procamp_123", { + * fields: "id,*budget" + * }) + * .then(({ campaign }) => { + * console.log(campaign) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async retrieve( id: string, query?: HttpTypes.AdminGetCampaignParams, @@ -28,6 +60,52 @@ export class Campaign { ) } + /** + * This method retrieves a paginated list of campaigns. It sends a request to the + * [List Campaigns](https://docs.medusajs.com/v2/api/admin#campaigns_getcampaigns) API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of campaigns. + * + * @example + * To retrieve the list of campaigns: + * + * ```ts + * sdk.admin.campaign.list() + * .then(({ campaigns, count, limit, offset }) => { + * console.log(campaigns) + * }) + * ``` + * + * 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.campaign.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ campaigns, count, limit, offset }) => { + * console.log(campaigns) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each campaign: + * + * ```ts + * sdk.admin.campaign.list({ + * fields: "id,*budget" + * }) + * .then(({ campaigns, count, limit, offset }) => { + * console.log(campaigns) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminGetCampaignsParams, headers?: ClientHeaders @@ -41,6 +119,22 @@ export class Campaign { ) } + /** + * This method creates a campaign. It sends a request to the + * [Create Campaign](https://docs.medusajs.com/v2/api/admin#campaigns_postcampaigns) API route. + * + * @param payload - The details of the campaign to create. + * @param headers - Headers to pass in the request + * @returns The campaign's details. + * + * @example + * sdk.admin.campaign.create({ + * name: "Summer Campaign" + * }) + * .then(({ campaign }) => { + * console.log(campaign) + * }) + */ async create( payload: HttpTypes.AdminCreateCampaign, headers?: ClientHeaders @@ -55,6 +149,23 @@ export class Campaign { ) } + /** + * This method updates a campaign. It sends a request to the + * [Update Campaign](https://docs.medusajs.com/v2/api/admin#campaigns_postcampaignsid) API route. + * + * @param id - The campaign's ID. + * @param payload - The data to update in the campaign. + * @param headers - Headers to pass in the request + * @returns The campaign's details. + * + * @example + * sdk.admin.campaign.update("procamp_123", { + * name: "Summer Campaign" + * }) + * .then(({ campaign }) => { + * console.log(campaign) + * }) + */ async update( id: string, payload: HttpTypes.AdminUpdateCampaign, @@ -70,6 +181,20 @@ export class Campaign { ) } + /** + * This method deletes a campaign by its ID. It sends a request to the + * [Delete Campaign](https://docs.medusajs.com/v2/api/admin#campaigns_deletecampaignsid) API route. + * + * @param id - The campaign's ID. + * @param headers - Headers to pass in the request + * @returns The deletion's details. + * + * @example + * sdk.admin.campaign.delete("procamp_123") + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async delete(id: string, headers?: ClientHeaders) { return await this.client.fetch>( `/admin/campaigns/${id}`, @@ -80,6 +205,16 @@ export class Campaign { ) } + /** + * This method manages the promotions of a campaign to either add or remove the association between them. + * It sends a request to the [Manage Promotions](https://docs.medusajs.com/v2/api/admin#campaigns_postcampaignsidpromotions) + * API route. + * + * @param id - The campaign's ID. + * @param payload - The promotions to add or remove associations to them. + * @param headers - Headers to pass in the request + * @returns The campaign's details. + */ async batchPromotions( id: string, payload: HttpTypes.AdminBatchLink, diff --git a/packages/core/js-sdk/src/admin/claim.ts b/packages/core/js-sdk/src/admin/claim.ts index fc64ef3944..fb64a7c413 100644 --- a/packages/core/js-sdk/src/admin/claim.ts +++ b/packages/core/js-sdk/src/admin/claim.ts @@ -15,6 +15,52 @@ export class Claim { this.client = client } + /** + * This method retrieves a paginated list of claims. It sends a request to the + * [List Claims](https://docs.medusajs.com/v2/api/admin#claims_getclaims) API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of claims. + * + * @example + * To retrieve the list of claims: + * + * ```ts + * sdk.admin.claim.list() + * .then(({ claims, count, limit, offset }) => { + * console.log(claims) + * }) + * ``` + * + * 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.claim.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ claims, count, limit, offset }) => { + * console.log(claims) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each claim: + * + * ```ts + * sdk.admin.claim.list({ + * fields: "id,*additional_items" + * }) + * .then(({ claims, count, limit, offset }) => { + * console.log(claims) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async list(query?: HttpTypes.AdminClaimListParams, headers?: ClientHeaders) { return await this.client.fetch( `/admin/claims`, @@ -25,9 +71,41 @@ export class Claim { ) } + /** + * This method retrieves a claim. It sends a request to the + * [Get Claim](https://docs.medusajs.com/v2/api/admin#claims_getclaimsid) API route. + * + * @param id - The claim's ID. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The claim's details. + * + * @example + * To retrieve a claim by its ID: + * + * ```ts + * sdk.admin.claim.retrieve("claim_123") + * .then(({ claim }) => { + * console.log(claim) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.claim.retrieve("claim_123", { + * fields: "id,*additional_items" + * }) + * .then(({ claim }) => { + * console.log(claim) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async retrieve( id: string, - query?: HttpTypes.AdminClaimParams, + query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { return await this.client.fetch( @@ -39,12 +117,30 @@ export class Claim { ) } + /** + * This method creates a claim. It sends a request to the + * [Create Claim](https://docs.medusajs.com/v2/api/admin#claims_postclaims) API route. + * + * @param body - The claim's details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The claim and order's details. + * + * @example + * sdk.admin.claim.create({ + * type: "refund", + * order_id: "order_123", + * }) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async create( body: HttpTypes.AdminCreateClaim, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims`, { method: "POST", @@ -55,6 +151,21 @@ export class Claim { ) } + /** + * This method cancels a claim. It sends a request to the + * [Cancel Claim](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidcancel) API route. + * + * @param id - The claim's ID. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The claim's details. + * + * @example + * sdk.admin.claim.cancel("claim_123") + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async cancel( id: string, query?: HttpTypes.SelectParams, @@ -70,13 +181,36 @@ export class Claim { ) } + /** + * This method adds items to the claim. It sends a request to the + * [Add Items](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidclaimitems) API route. + * + * @param id - The ID of the claim to add the items to. + * @param body - The items' details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The claim's details with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.addItems("claim_123", { + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ] + * }) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async addItems( id: string, body: HttpTypes.AdminAddClaimItems, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/claim-items`, { method: "POST", @@ -87,6 +221,32 @@ export class Claim { ) } + /** + * This method updates a claim item by the ID of the item's `WRITE_OFF_ITEM` action. It + * sends a request to the [Update Claim Item](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidclaimitemsaction_id) API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the order item's `WRITE_OFF_ITEM` action. + * @param body - The details to update. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The claim's details with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.updateItem( + * "claim_123", + * "ordchact_123", + * { + * quantity: 1 + * } + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async updateItem( id: string, actionId: string, @@ -94,7 +254,7 @@ export class Claim { query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/claim-items/${actionId}`, { method: "POST", @@ -105,13 +265,36 @@ export class Claim { ) } + /** + * This method removes a claim item from a claim by the ID of the item's `WRITE_OFF_ITEM` action. + * It sends a request to the [Remove Claim Item](https://docs.medusajs.com/v2/api/admin#claims_deleteclaimsidclaimitemsaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the order item's `WRITE_OFF_ITEM` action. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The claim's details with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.removeItem( + * "claim_123", + * "ordchact_123", + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async removeItem( id: string, actionId: string, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/claim-items/${actionId}`, { method: "DELETE", @@ -121,13 +304,41 @@ export class Claim { ) } + /** + * This method adds inbound (or return) items to the claim. These inbound items will have a `RETURN_ITEM` action. + * + * This method sends a request to the [Add Inbound Items](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidinbounditems) + * API route. + * + * @param id - The ID of the claim to add the inbound items to. + * @param body - The inbound items' details. + * @param query - Configure the fields to retrieve in the return. + * @param headers - Headers to pass in the request + * @returns The details of the return associated with the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.addInboundItems( + * "claim_123", + * { + * items: [ + * { + * id: "orli_123", + * quantity: 1 + * } + * ] + * }, + * ) + * .then(({ return: returnData }) => { + * console.log(returnData) + * }) + */ async addInboundItems( id: string, body: HttpTypes.AdminAddClaimInboundItems, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/inbound/items`, { method: "POST", @@ -138,6 +349,33 @@ export class Claim { ) } + /** + * This method updates an inbound (or return) item of a claim using the ID of the item's `RETURN_ITEM` action. + * It sends a request to the [Update Inbound Item](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidinbounditemsaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the return item's `RETURN_ITEM` action. + * @param body - The details to update in the inbound item. + * @param query - Configure the fields to retrieve in the return. + * @param headers - Headers to pass in the request + * @returns The details of the return associated wth the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.updateInboundItem( + * "claim_123", + * "ordchact_123", + * { + * quantity: 1 + * }, + * ) + * .then(({ return: returnData }) => { + * console.log(returnData) + * }) + */ async updateInboundItem( id: string, actionId: string, @@ -145,7 +383,7 @@ export class Claim { query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/inbound/items/${actionId}`, { method: "POST", @@ -156,13 +394,36 @@ export class Claim { ) } + /** + * This method removes an inbound (or return) item from a claim using the ID of the item's `RETURN_ITEM` action. + * It sends a request to the [Remove Inbound Item](https://docs.medusajs.com/v2/api/admin#claims_deleteclaimsidinbounditemsaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The ID of the return item's `RETURN_ITEM` action. + * @param query - Configure the fields to retrieve in the return. + * @param headers - Headers to pass in the request + * @returns The details of the return associated wth the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.removeInboundItem( + * "claim_123", + * "ordchact_123", + * ) + * .then(({ return: returnData }) => { + * console.log(returnData) + * }) + */ async removeInboundItem( id: string, actionId: string, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/inbound/items/${actionId}`, { method: "DELETE", @@ -172,13 +433,38 @@ export class Claim { ) } + /** + * This method adds an inbound (or return) shipping method to a claim. + * The inbound shipping method will have a `SHIPPING_ADD` action. + * + * This method sends a request to the [Add Inbound Shipping](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidinboundshippingmethod) + * API route. + * + * @param id - The claim's ID. + * @param body - The shipping method's details. + * @param query - Configure the fields to retrieve in the return. + * @param headers - Headers to pass in the request + * @returns The details of the return associated wth the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.addInboundShipping( + * "claim_123", + * { + * shipping_option_id: "so_123", + * custom_amount: 10 + * }, + * ) + * .then(({ return: returnData }) => { + * console.log(returnData) + * }) + */ async addInboundShipping( id: string, body: HttpTypes.AdminClaimAddInboundShipping, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/inbound/shipping-method`, { method: "POST", @@ -189,6 +475,33 @@ export class Claim { ) } + /** + * This method updates a shipping method for returning items in the claim using the ID of the method's `SHIPPING_ADD` action. + * It sends a request to the [Update Inbound Shipping](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidinboundshippingmethodaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the shipping method's `SHIPPING_ADD` action. + * @param body - The details to update in the shipping method + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.updateInboundShipping( + * "claim_123", + * "ordchact_123", + * { + * custom_amount: 10 + * }, + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async updateInboundShipping( id: string, actionId: string, @@ -196,7 +509,7 @@ export class Claim { query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/inbound/shipping-method/${actionId}`, { method: "POST", @@ -207,13 +520,36 @@ export class Claim { ) } + /** + * This method deletes a shipping method for returning items in the claim using the ID of the method's `SHIPPING_ADD` action. + * It sends a request to the [Remove Inbound Shipping](https://docs.medusajs.com/v2/api/admin#claims_deleteclaimsidinboundshippingmethodaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the shipping method's `SHIPPING_ADD` action. + * @param query - Configure the fields to retrieve in the return. + * @param headers - Headers to pass in the request + * @returns The details of the return associated wth the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.deleteInboundShipping( + * "claim_123", + * "ordchact_123", + * ) + * .then(({ return: returnData }) => { + * console.log(returnData) + * }) + */ async deleteInboundShipping( id: string, actionId: string, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/inbound/shipping-method/${actionId}`, { method: "DELETE", @@ -223,13 +559,38 @@ export class Claim { ) } + /** + * This method adds outbound (or new) items to a claim. These outbound items will have an `ITEM_ADD` action. + * It sends a request to the [Add Outbound Items](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidoutbounditems) + * API route. + * + * @param id - The ID of the claim to add the outbound items to. + * @param body - The items' details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.addOutboundItems( + * "claim_123", + * { + * items: [{ + * id: "orli_123", + * quantity: 1 + * }] + * }, + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async addOutboundItems( id: string, body: HttpTypes.AdminAddClaimOutboundItems, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/outbound/items`, { method: "POST", @@ -240,6 +601,33 @@ export class Claim { ) } + /** + * This method updates an outbound (or new) item of a claim using the ID of the item's `ITEM_ADD` action. + * It sends a request to the [Update Outbound Item](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidoutbounditemsaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the new claim item's `ITEM_ADD` action. + * @param body - The item's details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.updateOutboundItem( + * "claim_123", + * "ordchact_123", + * { + * quantity: 1 + * }, + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async updateOutboundItem( id: string, actionId: string, @@ -247,7 +635,7 @@ export class Claim { query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/outbound/items/${actionId}`, { method: "POST", @@ -258,13 +646,36 @@ export class Claim { ) } + /** + * This method removes an outbound (or new) item from a claim using the ID of the item's `ITEM_ADD` action. + * It sends a request to the [Remove Outbound Item](https://docs.medusajs.com/v2/api/admin#claims_deleteclaimsidoutbounditemsaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the new claim item's `ITEM_ADD` action. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.removeOutboundItem( + * "claim_123", + * "ordchact_123", + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async removeOutboundItem( id: string, actionId: string, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/outbound/items/${actionId}`, { method: "DELETE", @@ -274,13 +685,39 @@ export class Claim { ) } + /** + * This method adds outbound an outbound shipping method to a claim. + * The outbound shipping method will have a `SHIPPING_ADD` action. + * + * This method sends a request to the + * [Add Outbound Shipping](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidoutboundshippingmethod) + * API route. + * + * @param id - The claim's ID. + * @param body - The shipping method's details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * * sdk.admin.claim.addOutboundShipping( + * "claim_123", + * { + * shipping_option_id: "so_123", + * custom_amount: 10 + * }, + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async addOutboundShipping( id: string, body: HttpTypes.AdminClaimAddOutboundShipping, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/outbound/shipping-method`, { method: "POST", @@ -291,6 +728,33 @@ export class Claim { ) } + /** + * This method updates the shipping method for delivering outbound items in a claim using the ID of the method's `SHIPPING_ADD` action. + * It sends a request to the [Update Outbound Shipping](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidoutboundshippingmethodaction_id) + * API route. + * + * 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the shipping method's `SHIPPING_ADD` action. + * @param body - The shipping method's details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.updateOutboundShipping( + * "claim_123", + * "ordchact_123", + * { + * custom_amount: 10 + * }, + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async updateOutboundShipping( id: string, actionId: string, @@ -298,7 +762,7 @@ export class Claim { query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/outbound/shipping-method/${actionId}`, { method: "POST", @@ -309,13 +773,34 @@ export class Claim { ) } + /** + * This method deletes the shipping method for delivering outbound items in the claim using the ID of the 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. + * + * @param id - The claim's ID. + * @param actionId - The id of the shipping method's `SHIPPING_ADD` action. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.deleteOutboundShipping( + * "claim_123", + * "ordchact_123", + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async deleteOutboundShipping( id: string, actionId: string, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/outbound/shipping-method/${actionId}`, { method: "DELETE", @@ -325,13 +810,33 @@ export class Claim { ) } + /** + * This method confirms a claim request, applying its changes on the associated order. + * It sends a request to the [Confirm Claim Request](https://docs.medusajs.com/v2/api/admin#claims_postclaimsidrequest) + * API route. + * + * @param id - The claim's ID. + * @param body - The confirmation details. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The details of the claim and its associated return, with a preview of the order when the claim is applied. + * + * @example + * sdk.admin.claim.request( + * "claim_123", + * {}, + * ) + * .then(({ claim }) => { + * console.log(claim) + * }) + */ async request( id: string, body: HttpTypes.AdminRequestClaim, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/request`, { method: "POST", @@ -342,12 +847,30 @@ export class Claim { ) } + /** + * This method cancels a requested claim. It sends a request to the + * [Cancel Claim Request](https://docs.medusajs.com/v2/api/admin#claims_deleteclaimsidrequest) + * API route. + * + * @param id - The claim's ID. + * @param query - Configure the fields to retrieve in the claim. + * @param headers - Headers to pass in the request + * @returns The cancelation's details. + * + * @example + * sdk.admin.claim.cancelRequest( + * "claim_123", + * ) + * .then(({ deleted }) => { + * console.log(deleted) + * }) + */ async cancelRequest( id: string, query?: HttpTypes.SelectParams, headers?: ClientHeaders ) { - return await this.client.fetch( + return await this.client.fetch( `/admin/claims/${id}/request`, { method: "DELETE", diff --git a/packages/core/js-sdk/src/admin/currency.ts b/packages/core/js-sdk/src/admin/currency.ts index b62b2b704f..440a610014 100644 --- a/packages/core/js-sdk/src/admin/currency.ts +++ b/packages/core/js-sdk/src/admin/currency.ts @@ -14,6 +14,53 @@ export class Currency { this.client = client } + /** + * This method retrieves a paginated list of currencies. It sends a request to the + * [List Currencies](https://docs.medusajs.com/v2/api/admin#currencies_getcurrencies) + * API route. + * + * @param query - Filters and pagination configurations. + * @param headers - Headers to pass in the request. + * @returns The paginated list of currencies. + * + * @example + * To retrieve the list of currencies: + * + * ```ts + * sdk.admin.currency.list() + * .then(({ currencies, count, limit, offset }) => { + * console.log(currencies) + * }) + * ``` + * + * 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.currency.list({ + * limit: 10, + * offset: 10 + * }) + * .then(({ currencies, count, limit, offset }) => { + * console.log(currencies) + * }) + * ``` + * + * Using the `fields` query parameter, you can specify the fields and relations to retrieve + * in each currency: + * + * ```ts + * sdk.admin.currency.list({ + * fields: "code,symbol" + * }) + * .then(({ currencies, count, limit, offset }) => { + * console.log(currencies) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async list( query?: HttpTypes.AdminCurrencyListParams, headers?: ClientHeaders @@ -27,13 +74,45 @@ export class Currency { ) } + /** + * This method retrieves a currency by its code. It sends a request to the + * [Get Currency](https://docs.medusajs.com/v2/api/admin#currencies_getcurrenciescode) API route. + * + * @param code - The currency's code. + * @param query - Configure the fields to retrieve in the currency. + * @param headers - Headers to pass in the request + * @returns The currency's details. + * + * @example + * To retrieve a currency by its code: + * + * ```ts + * sdk.admin.currency.retrieve("usd") + * .then(({ currency }) => { + * console.log(currency) + * }) + * ``` + * + * To specify the fields and relations to retrieve: + * + * ```ts + * sdk.admin.currency.retrieve("usd", { + * fields: "code,symbol" + * }) + * .then(({ currency }) => { + * console.log(currency) + * }) + * ``` + * + * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/v2/api/store#select-fields-and-relations). + */ async retrieve( - id: string, + code: string, query?: HttpTypes.AdminCurrencyParams, headers?: ClientHeaders ) { return this.client.fetch( - `/admin/currencies/${id}`, + `/admin/currencies/${code}`, { headers, query, diff --git a/packages/core/types/src/http/api-key/admin/payloads.ts b/packages/core/types/src/http/api-key/admin/payloads.ts index cd2f8e7a30..53b5a10110 100644 --- a/packages/core/types/src/http/api-key/admin/payloads.ts +++ b/packages/core/types/src/http/api-key/admin/payloads.ts @@ -1,11 +1,20 @@ import { ApiKeyType } from "../../../api-key" export interface AdminCreateApiKey { + /** + * The API key's title. + */ title: string + /** + * The API key's type. + */ type: ApiKeyType } export interface AdminUpdateApiKey { + /** + * The API key's title. + */ title: string } diff --git a/packages/core/types/src/http/api-key/admin/queries.ts b/packages/core/types/src/http/api-key/admin/queries.ts index dea17f93a0..388edb3b92 100644 --- a/packages/core/types/src/http/api-key/admin/queries.ts +++ b/packages/core/types/src/http/api-key/admin/queries.ts @@ -5,15 +5,40 @@ import { FindParams } from "../../common" export interface AdminGetApiKeysParams extends FindParams, BaseFilterable { + /** + * Query or keywords to search the API key's searchable fields. + */ q?: string + /** + * Filter by API key ID(s). + */ id?: string | string[] + /** + * Filter by title(s). + */ title?: string | string[] + /** + * Filter by token(s). + */ token?: string | string[] + /** + * Filter by type. + */ type?: ApiKeyType + /** + * Apply filters on the API key's creation date. + */ created_at?: OperatorMap + /** + * Apply filters on the API key's update date. + */ updated_at?: OperatorMap + /** + * Apply filters on the API key's deletion date. + */ deleted_at?: OperatorMap + /** + * Apply filters on the API key's revocation date. + */ revoked_at?: OperatorMap - $and?: AdminGetApiKeysParams[] - $or?: AdminGetApiKeysParams[] } diff --git a/packages/core/types/src/http/api-key/admin/responses.ts b/packages/core/types/src/http/api-key/admin/responses.ts index 5bc1518fa6..b0633979f0 100644 --- a/packages/core/types/src/http/api-key/admin/responses.ts +++ b/packages/core/types/src/http/api-key/admin/responses.ts @@ -2,25 +2,68 @@ import { ApiKeyType } from "../../../api-key" import { DeleteResponse, PaginatedResponse } from "../../common" interface AdminApiKey { + /** + * The API key's ID. + */ id: string + /** + * The API key's token. + */ token: string + /** + * The redacted form of the token, useful + * for displaying the API key. + */ redacted: string + /** + * The API key's title. + */ title: string + /** + * The API key's type. + */ type: ApiKeyType + /** + * The date the API key was last used. + */ last_used_at: Date | null + /** + * The ID of the user that created the API key. + */ created_by: string + /** + * The date the API key was created. + */ created_at: Date + /** + * The date the API key was updated. + */ updated_at: Date + /** + * The ID of the user that revoked the API key. + */ revoked_by: string | null + /** + * The date the API key was revoked. + */ revoked_at: Date | null + /** + * The date the API key was deleted. + */ deleted_at: Date | null } export interface AdminApiKeyResponse { + /** + * The API key's details. + */ api_key: AdminApiKey } export type AdminApiKeyListResponse = PaginatedResponse<{ + /** + * The list of API keys. + */ api_keys: AdminApiKey[] }> diff --git a/packages/core/types/src/http/campaign/admin/payloads.ts b/packages/core/types/src/http/campaign/admin/payloads.ts index 86a18f16b8..21c1295421 100644 --- a/packages/core/types/src/http/campaign/admin/payloads.ts +++ b/packages/core/types/src/http/campaign/admin/payloads.ts @@ -1,29 +1,103 @@ import { CampaignBudgetTypeValues } from "../../../promotion" export interface AdminCreateCampaign { + /** + * The campaign's name. + */ name?: string + /** + * The campaign's description. + */ description?: string + /** + * The campaign's currency code. + * + * @example + * usd + */ currency?: string | null + /** + * The campaign's identifier. + */ campaign_identifier?: string + /** + * The date the campaign and its promotions start at. + */ starts_at?: Date | null + /** + * The date the campaign and its promotions end at. + */ ends_at?: Date | null + /** + * The campaign's budget. + */ budget?: { + /** + * The budget's type. `spend` means the limit is set on the total amount discounted by the campaign's promotions; + * `usage` means the limit is set on the total number of times the campaign's promotions can be used. + */ type?: CampaignBudgetTypeValues + /** + * The budget's currency code. + * + * @example + * usd + */ currency_code?: string | null + /** + * The budget's limit. + */ limit?: number | null } | null } export interface AdminUpdateCampaign { + /** + * The campaign's name. + */ name?: string + /** + * The campaign's description. + */ description?: string + /** + * The campaign's currency code. + * + * @example + * usd + */ currency?: string | null + /** + * The campaign's identifier. + */ campaign_identifier?: string + /** + * The date the campaign and its promotions start at. + */ starts_at?: Date | null + /** + * The date the campaign and its promotions end at. + */ ends_at?: Date | null + /** + * The campaign's budget. + */ budget?: { + /** + * The budget's type. `spend` means the limit is set on the total amount discounted by the campaign's promotions; + * `usage` means the limit is set on the total number of times the campaign's promotions can be used. + */ type?: CampaignBudgetTypeValues + /** + * The budget's currency code. + * + * @example + * usd + */ currency_code?: string | null + /** + * The budget's limit. + */ limit?: number | null } | null } diff --git a/packages/core/types/src/http/campaign/admin/responses.ts b/packages/core/types/src/http/campaign/admin/responses.ts index 6580ed1e68..fe770e6581 100644 --- a/packages/core/types/src/http/campaign/admin/responses.ts +++ b/packages/core/types/src/http/campaign/admin/responses.ts @@ -2,18 +2,66 @@ import { CampaignBudgetTypeValues } from "../../../promotion" import { DeleteResponse, PaginatedResponse } from "../../common" export interface AdminCampaign { + /** + * The campaign's ID. + */ id: string + /** + * The campaign's name. + */ name: string + /** + * The campaign's description. + */ description: string + /** + * The campaign's currency code. + * + * @example + * usd + */ currency: string + /** + * The campaign's identifier. + */ campaign_identifier: string + /** + * The date the campaign and its promotions start at. + */ starts_at: string + /** + * The date the campaign and its promotions end at. + */ ends_at: string + /** + * The campaign's budget. + */ budget: { + /** + * The budget's ID. + */ id: string + /** + * The budget's type. `spend` means the limit is set on the total amount discounted by the campaign's promotions; + * `usage` means the limit is set on the total number of times the campaign's promotions can be used. + */ type: CampaignBudgetTypeValues + /** + * The budget's currency code. + * + * @example + * usd + */ currency_code: string + /** + * The budget's limit. + */ limit: number + /** + * How much of the budget has been used. If the limit is `spend`, this property holds the total amount + * discounted so far. If the limit is `usage`, it holds the number of times the campaign's + * promotions have been used so far. + */ used: number } created_at: string @@ -26,6 +74,9 @@ export type AdminCampaignListResponse = PaginatedResponse<{ }> export interface AdminCampaignResponse { + /** + * The campaign's details. + */ campaign: AdminCampaign } diff --git a/packages/core/types/src/http/claim/admin/entities.ts b/packages/core/types/src/http/claim/admin/entities.ts index 6369bd0692..bbdcf294b6 100644 --- a/packages/core/types/src/http/claim/admin/entities.ts +++ b/packages/core/types/src/http/claim/admin/entities.ts @@ -3,7 +3,16 @@ import { AdminReturn } from "../../return" import { BaseClaim } from "../common" export interface AdminClaim extends BaseClaim { + /** + * The order this claim is created for. + */ order: AdminOrder + /** + * The associated return. + */ return: AdminReturn + /** + * The shipping methods of the claim's additional items. + */ shipping_methods?: AdminOrderShippingMethod[] } diff --git a/packages/core/types/src/http/claim/admin/payloads.ts b/packages/core/types/src/http/claim/admin/payloads.ts index b5e8f8cdad..e99f665cf0 100644 --- a/packages/core/types/src/http/claim/admin/payloads.ts +++ b/packages/core/types/src/http/claim/admin/payloads.ts @@ -6,41 +6,112 @@ enum ClaimReason { } interface AdminClaimAddItems { + /** + * The items to add to the claim. + */ items: { + /** + * The ID of the item in the order. + */ id: string + /** + * The quantity to claim. + */ quantity: number + /** + * The reason for adding this item to the claim. + */ reason?: ClaimReason + /** + * The claim item's description. + */ description?: string + /** + * An internal note viewed by admin users only. + */ internal_note?: string }[] } interface AdminClaimUpdateItem { + /** + * The item's claimed quantity. + */ quantity?: number + /** + * The ID of the associated claim reason. + */ reason_id?: string | null + /** + * The claim item's description. + */ description?: string + /** + * An internal note viewed by admin users only. + */ internal_note?: string | null } interface AdminClaimAddShippingMethod { + /** + * The ID of the shipping option to create the method from. + */ shipping_option_id: string + /** + * A custom amount to use instead of the shipping option's amount. + */ custom_amount?: number + /** + * The method's description. + */ description?: string + /** + * An internal note viewed by admin users only. + */ internal_note?: string + /** + * Key-value pairs of custom data. + */ metadata?: Record | null } interface AdminClaimUpdateShippingMethod { + /** + * A custom amount to use instead of the shipping option's amount. + */ custom_amount?: number | null + /** + * An internal note viewed by admin users only. + */ internal_note?: string + /** + * Key-value pairs of custom data. + */ metadata?: Record | null } export interface AdminCreateClaim { + /** + * The claim's type. If `refund`, it means the claim's items + * are returned and the customer is refunded. If `replace`, it + * means the merchant will send new items in place of the returned items. + */ type: "refund" | "replace" + /** + * The ID of the order this claim is created for. + */ order_id: string + /** + * The claim's description. + */ description?: string + /** + * An internal note viewed by admin users only. + */ internal_note?: string + /** + * Key-value pairs of custom data. + */ metadata?: Record | null } diff --git a/packages/core/types/src/http/claim/admin/queries.ts b/packages/core/types/src/http/claim/admin/queries.ts index 0583a01a31..7a6abfcd56 100644 --- a/packages/core/types/src/http/claim/admin/queries.ts +++ b/packages/core/types/src/http/claim/admin/queries.ts @@ -4,9 +4,7 @@ import { BaseClaimListParams } from "../common" export interface AdminClaimListParams extends BaseClaimListParams, - BaseFilterable { - deleted_at?: OperatorMap -} + BaseFilterable { } export interface AdminClaimParams extends SelectParams { id?: string | string[] diff --git a/packages/core/types/src/http/claim/admin/responses.ts b/packages/core/types/src/http/claim/admin/responses.ts index f974b8b27c..049f1e5d11 100644 --- a/packages/core/types/src/http/claim/admin/responses.ts +++ b/packages/core/types/src/http/claim/admin/responses.ts @@ -5,26 +5,50 @@ import { AdminReturn } from "../../return" import { AdminClaim } from "./entities" export interface AdminClaimResponse { + /** + * The claim's details. + */ claim: AdminClaim } export interface AdminClaimListResponse extends PaginatedResponse<{ + /** + * The list of claims. + */ claims: AdminClaim[] }> {} export interface AdminClaimOrderResponse { + /** + * The order's details. + */ order: OrderDTO + /** + * The claim's details. + */ claim: AdminClaim } export interface AdminClaimPreviewResponse { + /** + * Preview of the order when the claim is applied. + */ order_preview: AdminOrderPreview + /** + * The claim's details. + */ claim: AdminClaim } export interface AdminClaimReturnPreviewResponse { + /** + * Preview of the order when the claim is applied. + */ order_preview: AdminOrderPreview + /** + * The return's details. + */ return: AdminReturn } diff --git a/packages/core/types/src/http/claim/common.ts b/packages/core/types/src/http/claim/common.ts index 01257f3cd4..ce5a372608 100644 --- a/packages/core/types/src/http/claim/common.ts +++ b/packages/core/types/src/http/claim/common.ts @@ -23,34 +23,115 @@ export interface BaseClaimItem { } export interface BaseClaim { + /** + * The claim's ID. + */ id: string + /** + * The claim's type. + */ type: OrderClaimType + /** + * The ID of the order this claim was created for. + */ order_id: string + /** + * The ID of the associated return. + */ return_id?: string + /** + * The claim's display ID. + */ display_id: number + /** + * The version of the order when the claim is applied. + */ order_version: string + /** + * The amount to be refunded due to this claim. + */ refund_amount?: number + /** + * The ID of the user that created this claim. + */ created_by?: string + /** + * The date the claim was created. + */ created_at: Date | string + /** + * The date the claim was updated. + */ updated_at: Date | string + /** + * The date the claim was canceled. + */ canceled_at: Date | string + /** + * The date the claim was deleted. + */ deleted_at?: Date | string + /** + * The claim's additional items if its `type` is `replace`. + */ additional_items: BaseClaimItem[] + /** + * The claim's items. + */ claim_items: BaseClaimItem[] + /** + * Whether to notify the customer about changes in the claim. + */ no_notification?: boolean + /** + * The order this claim was created for. + */ order?: BaseOrder + /** + * The associated return. + */ return?: BaseReturn + /** + * The shipping methods of the claim's additional items. + */ shipping_methods?: BaseOrderShippingMethod[] + /** + * The claim's transactions. + */ transactions?: BaseOrderTransaction[] + /** + * Key-value pairs of custom data. + */ metadata?: Record | null } export interface BaseClaimListParams extends FindParams { + /** + * Query or keywords to search the claim's searchable fields. + */ q?: string + /** + * Filter by ID(s). + */ id?: string | string[] + /** + * Retrieve the claims of the specified order ID(s). + */ order_id?: string | string[] + /** + * Filter by status(es). + */ status?: string | string[] + /** + * Filter by the claim's creation date. + */ created_at?: OperatorMap + /** + * Filter by the claim's update date. + */ updated_at?: OperatorMap + /** + * Filter by the claim's deletion date. + */ deleted_at?: OperatorMap } diff --git a/packages/core/types/src/http/common/request.ts b/packages/core/types/src/http/common/request.ts index 786d5da45d..88fd0f9a8a 100644 --- a/packages/core/types/src/http/common/request.ts +++ b/packages/core/types/src/http/common/request.ts @@ -26,6 +26,12 @@ export interface FindParams extends SelectParams { } export interface AdminBatchLink { + /** + * The items to create an association to. + */ add?: string[] + /** + * The items to remove association from. + */ remove?: string[] } diff --git a/packages/core/types/src/http/currency/admin/queries.ts b/packages/core/types/src/http/currency/admin/queries.ts index 8b537900dc..50d15a792b 100644 --- a/packages/core/types/src/http/currency/admin/queries.ts +++ b/packages/core/types/src/http/currency/admin/queries.ts @@ -6,6 +6,12 @@ export interface AdminCurrencyParams extends SelectParams {} export interface AdminCurrencyListParams extends FindParams, BaseFilterable { + /** + * Query or keyword to search the currency's searchable fields. + */ q?: string + /** + * Filter by currency code(s). + */ code?: string | string[] } diff --git a/packages/core/types/src/http/currency/admin/responses.ts b/packages/core/types/src/http/currency/admin/responses.ts index 29bf4e0d49..dcb8a29109 100644 --- a/packages/core/types/src/http/currency/admin/responses.ts +++ b/packages/core/types/src/http/currency/admin/responses.ts @@ -2,8 +2,16 @@ import { PaginatedResponse } from "../../common" import { AdminCurrency } from "./entities" export interface AdminCurrencyResponse { + /** + * The currency's details. + */ currency: AdminCurrency } export interface AdminCurrencyListResponse - extends PaginatedResponse<{ currencies: AdminCurrency[] }> {} + extends PaginatedResponse<{ + /** + * The list of currencies + */ + currencies: AdminCurrency[] + }> {} diff --git a/packages/core/types/src/http/currency/common.ts b/packages/core/types/src/http/currency/common.ts index d9e1ef8b7f..966b13af4d 100644 --- a/packages/core/types/src/http/currency/common.ts +++ b/packages/core/types/src/http/currency/common.ts @@ -1,11 +1,47 @@ export interface BaseCurrency { + /** + * The currency's code. + * + * @example + * usd + */ code: string + /** + * The currency's symbol. + * + * @example + * $ + */ symbol: string + /** + * The currency's symbol in its native language or country. + * + * @example + * $ + */ symbol_native: string + /** + * The currency's name. + */ name: string + /** + * The number of digits after the decimal for prices in this currency. + */ decimal_digits: number + /** + * The rounding percision applied on prices in this currency. + */ rounding: number + /** + * 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 } diff --git a/packages/core/types/src/http/order/admin/entities.ts b/packages/core/types/src/http/order/admin/entities.ts index f2c871b499..0207504050 100644 --- a/packages/core/types/src/http/order/admin/entities.ts +++ b/packages/core/types/src/http/order/admin/entities.ts @@ -32,10 +32,25 @@ export interface AdminOrderChange BaseOrderChange, "order" | "claim" | "return_order" | "exchange" | "actions" > { + /** + * The order's details. + */ order: AdminOrder + /** + * The claim's details. + */ claim: AdminClaim + /** + * The return's details. + */ return_order: AdminReturn + /** + * The exchange's details. + */ exchange: AdminExchange + /** + * The order change action's details. + */ actions: AdminOrderChangeAction[] } @@ -54,7 +69,13 @@ export interface AdminOrderItem { export interface AdminOrderChangeAction extends Omit { + /** + * The order change's details. + */ order_change: AdminOrderChange + /** + * The order's details. + */ order: AdminOrder | null } @@ -87,9 +108,21 @@ export interface AdminOrderShippingMethod extends BaseOrderShippingMethod {} export interface AdminOrderPreview extends Omit { + /** + * The total amount for the items requested to be returned. + */ return_requested_total: number + /** + * The details of the changes on the order. + */ order_change: AdminOrderChange + /** + * The order's items. + */ items: (AdminOrderLineItem & { actions?: AdminOrderChangeAction[] })[] + /** + * The order's shipping methods. + */ shipping_methods: (AdminOrderShippingMethod & { actions?: AdminOrderChangeAction[] })[]