diff --git a/.changeset/dull-grapes-act.md b/.changeset/dull-grapes-act.md new file mode 100644 index 0000000000..0e2e4b7b3f --- /dev/null +++ b/.changeset/dull-grapes-act.md @@ -0,0 +1,13 @@ +--- +"@medusajs/client-types": patch +"medusa-react": patch +"@medusajs/medusa-js": patch +"@medusajs/medusa": patch +"@medusajs/types": patch +--- + +fix(@medusajs/client-types): Fix types and TSDocs +fix(medusa-react): Fix response type of Publishable API Key's list sales channels. +fix(@medusajs/medusa-js): Fix incorrect parameter and response types. +fix(@medusajs/medusa): Fix incorrect types and add TSDocs +fix(@medusajs/types): Fix incorrect types and add TSDocs \ No newline at end of file diff --git a/docs-util/packages/scripts/package.json b/docs-util/packages/scripts/package.json index 8d79484e3f..840eb89798 100644 --- a/docs-util/packages/scripts/package.json +++ b/docs-util/packages/scripts/package.json @@ -25,12 +25,12 @@ "typedoc": "0.25.1", "typedoc-config": "*", "typedoc-monorepo-link-types": "^0.0.2", + "typedoc-plugin-custom": "*", "typedoc-plugin-frontmatter": "*", "typedoc-plugin-markdown": "3.16.0", "typedoc-plugin-markdown-medusa": "*", "typedoc-plugin-merge-modules": "5.1.0", "typedoc-plugin-missing-exports": "^2.1.0", - "typedoc-plugin-modules": "*", "typedoc-plugin-reference-excluder": "1.1.3", "typedoc-plugin-rename-defaults": "^0.6.6", "typescript": "^5.2.2" diff --git a/docs-util/packages/typedoc-config/_base.js b/docs-util/packages/typedoc-config/_base.js index d33bad6b31..21cd7abb9e 100644 --- a/docs-util/packages/typedoc-config/_base.js +++ b/docs-util/packages/typedoc-config/_base.js @@ -1,4 +1,18 @@ +/* eslint-disable @typescript-eslint/no-var-requires */ +const path = require("path") + +const pathPrefix = path.join(__dirname, "..", "..", "..") + +/** @type {import('typedoc').TypeDocOptions} */ module.exports = { + // extends: [typedocConfig], plugin: ["typedoc-plugin-markdown-medusa"], readme: "none", + eslintPathName: path.join( + pathPrefix, + "www/packages/eslint-config-docs/content.js" + ), + pluginsResolvePath: path.join(pathPrefix, "www"), + // Uncomment this when debugging + // showConfig: true, } diff --git a/docs-util/packages/typedoc-config/_modules.js b/docs-util/packages/typedoc-config/_modules.js index 8c776926bf..72fb4a48d7 100644 --- a/docs-util/packages/typedoc-config/_modules.js +++ b/docs-util/packages/typedoc-config/_modules.js @@ -70,10 +70,9 @@ module.exports = ({ ...globalTypedocOptions, entryPoints: [path.join(pathPrefix, entryPointPath)], out: [path.join(pathPrefix, outPath)], - tsconfig: path.join( - pathPrefix, - tsconfigPath || "packages/types/tsconfig.json" - ), + tsconfig: tsconfigPath.length + ? path.join(pathPrefix, tsconfigPath) + : path.join(__dirname, "extended-tsconfig", "types.json"), name: `${moduleName} Reference`, indexTitle: `${moduleName} Reference`, entryDocument: "index.md", @@ -82,7 +81,7 @@ module.exports = ({ hideBreadcrumbs: true, plugin: [ ...globalTypedocOptions.plugin, - "typedoc-plugin-modules", + "typedoc-plugin-custom", "typedoc-plugin-rename-defaults", "typedoc-plugin-frontmatter", ], diff --git a/docs-util/packages/typedoc-config/entities.js b/docs-util/packages/typedoc-config/entities.js index 54264a7fb0..f128a48bd7 100644 --- a/docs-util/packages/typedoc-config/entities.js +++ b/docs-util/packages/typedoc-config/entities.js @@ -8,7 +8,7 @@ module.exports = { ...globalTypedocOptions, entryPoints: [path.join(pathPrefix, "packages/medusa/src/models/index.ts")], out: [path.join(pathPrefix, "www/apps/docs/content/references/entities")], - tsconfig: path.join(pathPrefix, "packages/medusa/tsconfig.json"), + tsconfig: path.join(__dirname, "extended-tsconfig", "medusa.json"), name: "Entities Reference", indexTitle: "Entities Reference", entryDocument: "_index.mdx", diff --git a/docs-util/packages/typedoc-config/extended-tsconfig/js-client.json b/docs-util/packages/typedoc-config/extended-tsconfig/js-client.json new file mode 100644 index 0000000000..641fb436af --- /dev/null +++ b/docs-util/packages/typedoc-config/extended-tsconfig/js-client.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json.schemastore.org/tsconfig", + "extends": [ + "../../../../packages/medusa-js/tsconfig.json" + ] +} \ No newline at end of file diff --git a/docs-util/packages/typedoc-config/extended-tsconfig/medusa.json b/docs-util/packages/typedoc-config/extended-tsconfig/medusa.json new file mode 100644 index 0000000000..f6720ce60e --- /dev/null +++ b/docs-util/packages/typedoc-config/extended-tsconfig/medusa.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json.schemastore.org/tsconfig", + "extends": [ + "../../../../packages/medusa/tsconfig.json" + ] +} \ No newline at end of file diff --git a/docs-util/packages/typedoc-config/extended-tsconfig/tsdoc.json b/docs-util/packages/typedoc-config/extended-tsconfig/tsdoc.json new file mode 100644 index 0000000000..06df94198f --- /dev/null +++ b/docs-util/packages/typedoc-config/extended-tsconfig/tsdoc.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["typedoc/tsdoc.json"], + "tagDefinitions": [ + { + "tagName": "@featureFlag", + "syntaxKind": "block" + }, + { + "tagName": "@expandable", + "syntaxKind": "modifier" + }, + { + "tagName": "@schema", + "syntaxKind": "block" + }, + { + "tagName": "@apiIgnore", + "syntaxKind": "modifier" + } + ] +} \ No newline at end of file diff --git a/docs-util/packages/typedoc-config/extended-tsconfig/types.json b/docs-util/packages/typedoc-config/extended-tsconfig/types.json new file mode 100644 index 0000000000..d384d9edbf --- /dev/null +++ b/docs-util/packages/typedoc-config/extended-tsconfig/types.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json.schemastore.org/tsconfig", + "extends": [ + "../../../../packages/types/tsconfig.json" + ] +} \ No newline at end of file diff --git a/docs-util/packages/typedoc-config/js-client.js b/docs-util/packages/typedoc-config/js-client.js index 916ee03e80..4b2ca16dce 100644 --- a/docs-util/packages/typedoc-config/js-client.js +++ b/docs-util/packages/typedoc-config/js-client.js @@ -4,12 +4,35 @@ const globalTypedocOptions = require("./_base") const pathPrefix = path.join(__dirname, "..", "..", "..") +const defaultFormattingOptions = { + showCommentsAsHeader: true, + sections: { + member_sources_definedIn: false, + reflection_hierarchy: false, + member_signature_typeParameters: false, + member_signature_sources: false, + member_signature_title: false, + member_signature_returns: false, + }, + parameterStyle: "component", + parameterComponent: "ParameterTypes", + mdxImports: [ + `import ParameterTypes from "@site/src/components/ParameterTypes"`, + ], + reflectionGroups: { + Constructors: false, + }, + frontmatterData: { + displayed_sidebar: "jsClientSidebar", + }, +} + +/** @type {import('typedoc').TypeDocOptions} */ module.exports = { ...globalTypedocOptions, entryPoints: [path.join(pathPrefix, "packages/medusa-js/src/resources")], - entryPointStrategy: "expand", out: [path.join(pathPrefix, "www/apps/docs/content/references/js-client")], - tsconfig: path.join(pathPrefix, "packages/medusa-js/tsconfig.json"), + tsconfig: path.join(__dirname, "extended-tsconfig", "js-client.json"), name: "JS Client Reference", indexTitle: "JS Client Reference", entryDocument: "_index.mdx", @@ -17,35 +40,26 @@ module.exports = { hideBreadcrumbs: true, plugin: [ ...globalTypedocOptions.plugin, - "typedoc-plugin-reference-excluder", - "typedoc-plugin-frontmatter", "typedoc-plugin-rename-defaults", - "typedoc-plugin-modules", + "typedoc-plugin-custom", ], exclude: [ path.join(pathPrefix, "packages/medusa-js/src/resources/base.ts"), path.join(pathPrefix, "node_modules/**"), - path.join(pathPrefix, "packages/**/node_modules"), ], - excludeConstructors: true, - frontmatterData: { - displayed_sidebar: "jsClientSidebar", - }, internalModule: "internal", formatting: { - "*": { - showCommentsAsHeader: true, - sections: { - member_sources_definedIn: false, - reflection_hierarchy: false, + "*": defaultFormattingOptions, + "^classes/": { + ...defaultFormattingOptions, + frontmatterData: { + ...defaultFormattingOptions.frontmatterData, + slug: "/references/js-client/{{alias}}", }, - parameterStyle: "component", - parameterComponent: "ParameterTypes", - mdxImports: [ - `import ParameterTypes from "@site/src/components/ParameterTypes"`, - ], }, }, objectLiteralTypeDeclarationStyle: "component", mdxOutput: true, + maxLevel: 4, + ignoreApi: true, } diff --git a/docs-util/packages/typedoc-config/package.json b/docs-util/packages/typedoc-config/package.json index 2942c2c8d3..020059a2e0 100644 --- a/docs-util/packages/typedoc-config/package.json +++ b/docs-util/packages/typedoc-config/package.json @@ -5,6 +5,9 @@ "publishConfig": { "access": "public" }, + "peerDependencies": { + "typedoc": "0.25.x" + }, "main": "_base.js", "version": "0.0.0" } diff --git a/docs-util/packages/typedoc-config/services.js b/docs-util/packages/typedoc-config/services.js index aa59b445ca..565b865620 100644 --- a/docs-util/packages/typedoc-config/services.js +++ b/docs-util/packages/typedoc-config/services.js @@ -8,7 +8,7 @@ module.exports = { ...globalTypedocOptions, entryPoints: [path.join(pathPrefix, "packages/medusa/src/services/index.ts")], out: [path.join(pathPrefix, "www/apps/docs/content/references/services")], - tsconfig: path.join(pathPrefix, "packages/medusa/tsconfig.json"), + tsconfig: path.join(__dirname, "extended-tsconfig", "medusa.json"), name: "Services Reference", indexTitle: "Services Reference", entryDocument: "index.md", diff --git a/docs-util/packages/typedoc-plugin-frontmatter/.gitignore b/docs-util/packages/typedoc-plugin-custom/.gitignore similarity index 100% rename from docs-util/packages/typedoc-plugin-frontmatter/.gitignore rename to docs-util/packages/typedoc-plugin-custom/.gitignore diff --git a/docs-util/packages/typedoc-plugin-custom/README.md b/docs-util/packages/typedoc-plugin-custom/README.md new file mode 100644 index 0000000000..1a0b154b9d --- /dev/null +++ b/docs-util/packages/typedoc-plugin-custom/README.md @@ -0,0 +1,44 @@ +# typedoc-plugin-custom + +A Typedoc plugin that combines utility plugins for documenting references. + +## Configurations + +### Resolve Reference Configurations + +The [`resolve-reference-plugin`](./src/resolve-references-plugin.ts) imitates the [`typedoc-plugin-missing-exports`](https://www.npmjs.com/package/typedoc-plugin-missing-exports) plugin. So, it accepts the same options as the [`typedoc-plugin-missing-exports`](https://www.npmjs.com/package/typedoc-plugin-missing-exports) plugin. + +### Frontmatter + +`frontmatterData` is an object of key-value pairs. If none provided, no frontmatter variables will be added to the Markdown files. + +An example of passing it in a JavaScript configuration file: + +```js +frontmatterData: { + displayed_sidebar: "jsClientSidebar", +}, +``` + +### API Ignore + +The `ignoreApi` option is a boolean that indicates whether reflections with the `@apiIgnore` tag should be ignored. If enabled, reflections having this tag are removed from the generated documentation. If disabled (which is the default), the `@apiIgnore` tag is removed from the reflection to ensure it's not shown in the generated documentation. + +### ESLint + +If the `eslintPathName` option is set, code snippets provided in `@example` tag are linted based on the documentation's ESLint rules. + +The following options are useful for linting: + +- `eslintPathName`: The path to the ESLint configuration file. +- `pluginsResolvePath`: The path to resolve plugins used in the ESLint configuration files. + +--- + +## Build the Plugin + +Before using any command that makes use of this plugin, make sure to run the `build` command: + +```bash +yarn build +``` diff --git a/docs-util/packages/typedoc-plugin-modules/package.json b/docs-util/packages/typedoc-plugin-custom/package.json similarity index 83% rename from docs-util/packages/typedoc-plugin-modules/package.json rename to docs-util/packages/typedoc-plugin-custom/package.json index 3c1d2dfffc..d584fad384 100644 --- a/docs-util/packages/typedoc-plugin-modules/package.json +++ b/docs-util/packages/typedoc-plugin-custom/package.json @@ -1,5 +1,5 @@ { - "name": "typedoc-plugin-modules", + "name": "typedoc-plugin-custom", "private": true, "version": "0.0.0", "license": "MIT", @@ -32,7 +32,10 @@ "typedoc" ], "dependencies": { + "eslint": "^8.53.0", "glob": "^10.3.10", - "typedoc-plugin-markdown": "^3.16.0" + "typedoc-plugin-markdown": "^3.16.0", + "utils": "*", + "yaml": "^2.3.3" } } diff --git a/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts b/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts new file mode 100644 index 0000000000..a4075b1d06 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts @@ -0,0 +1,30 @@ +import { + Application, + Context, + Converter, + ParameterType, + ReflectionKind, +} from "typedoc" + +export function load(app: Application) { + app.options.addDeclaration({ + name: "ignoreApi", + help: "Whether to ignore items with the `@apiIgnore` tag.", + type: ParameterType.Boolean, // The default + defaultValue: false, + }) + + app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => { + for (const reflection of context.project.getReflectionsByKind( + ReflectionKind.All + )) { + if (reflection.comment?.hasModifier("@apiIgnore")) { + if (app.options.getValue("ignoreApi")) { + context.project.removeReflection(reflection) + } else { + reflection.comment.removeModifier(`@apiIgnore`) + } + } + } + }) +} diff --git a/docs-util/packages/typedoc-plugin-custom/src/eslint-example.ts b/docs-util/packages/typedoc-plugin-custom/src/eslint-example.ts new file mode 100644 index 0000000000..6280ee5056 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-custom/src/eslint-example.ts @@ -0,0 +1,65 @@ +import { ESLint } from "eslint" +import { + Application, + Context, + Converter, + ParameterType, + ReflectionKind, +} from "typedoc" + +export function load(app: Application) { + app.options.addDeclaration({ + name: "eslintPathName", + help: "The path to the ESLint configurations to apply.", + type: ParameterType.String, + }) + app.options.addDeclaration({ + name: "pluginsResolvePath", + help: "The path to resolve plugins used in the ESLint configurations.", + type: ParameterType.String, + }) + app.converter.on(Converter.EVENT_RESOLVE_BEGIN, async (context: Context) => { + const eslintConfigPath = app.options.getValue("eslintPathName") as string + const pluginsResolvePath = app.options.getValue( + "pluginsResolvePath" + ) as string + if (!eslintConfigPath) { + return + } + const eslint = new ESLint({ + overrideConfigFile: eslintConfigPath, + resolvePluginsRelativeTo: pluginsResolvePath, + fix: true, + }) + for (const reflection of context.project.getReflectionsByKind( + ReflectionKind.All + )) { + const example = reflection.comment?.getTag(`@example`) + if (example) { + await Promise.all( + example.content + .filter((exampleContent) => exampleContent.kind === "code") + .map(async (exampleContent) => { + const matchedCodeSnippets = exampleContent.text.matchAll( + /```ts(?[\s\S.]*)```/g + ) + for (const matchedCodeSnippet of matchedCodeSnippets) { + if (!matchedCodeSnippet.groups?.code) { + return + } + + const result = await eslint.lintText( + matchedCodeSnippet.groups.code + ) + + exampleContent.text = + result.length > 0 && result[0].output + ? "```ts\n" + result[0].output + "```" + : exampleContent.text + } + }) + ) + } + } + }) +} diff --git a/docs-util/packages/typedoc-plugin-frontmatter/src/index.ts b/docs-util/packages/typedoc-plugin-custom/src/frontmatter-plugin.ts similarity index 100% rename from docs-util/packages/typedoc-plugin-frontmatter/src/index.ts rename to docs-util/packages/typedoc-plugin-custom/src/frontmatter-plugin.ts diff --git a/docs-util/packages/typedoc-plugin-custom/src/index.ts b/docs-util/packages/typedoc-plugin-custom/src/index.ts new file mode 100644 index 0000000000..7c4bf33481 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-custom/src/index.ts @@ -0,0 +1,14 @@ +import { Application } from "typedoc" +import { load as resolveReferencesPluginLoad } from "./resolve-references-plugin" +import { load as frontmatterPlugin } from "./frontmatter-plugin" +import { load as parseOasSchemaPlugin } from "./parse-oas-schema-plugin" +import { load as apiIgnorePlugin } from "./api-ignore" +import { load as eslintExamplePlugin } from "./eslint-example" + +export function load(app: Application) { + resolveReferencesPluginLoad(app) + frontmatterPlugin(app) + parseOasSchemaPlugin(app) + apiIgnorePlugin(app) + eslintExamplePlugin(app) +} diff --git a/docs-util/packages/typedoc-plugin-custom/src/parse-oas-schema-plugin.ts b/docs-util/packages/typedoc-plugin-custom/src/parse-oas-schema-plugin.ts new file mode 100644 index 0000000000..116daea758 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-custom/src/parse-oas-schema-plugin.ts @@ -0,0 +1,234 @@ +import { + Application, + Comment, + CommentDisplayPart, + CommentTag, + Context, + Converter, + DeclarationReflection, + Reflection, + ReflectionKind, + SomeType, +} from "typedoc" +import { parse } from "yaml" +import { getTypeChildren } from "utils" + +// a simplified schema type +// mainly focusing on properties used +// within this plugin +type Schema = { + description?: string + properties?: SchemaProperties + allOf?: SchemaProperty[] + oneOf?: SchemaProperty[] +} + +type SchemaProperties = { + [k: string]: SchemaProperty +} + +type SchemaProperty = { + description?: string + "x-expandable"?: string + "x-featureFlag"?: string + default?: string + items?: Schema + properties?: SchemaProperties + allOf?: SchemaProperty[] + oneOf?: SchemaProperty[] +} + +export function load(app: Application) { + const definedSchemas = new Map() + + // Since some files, such as models, include the + // `@schema` declaration at the end of the file, i.e. not + // before the related class/type/interface, this extracts + // those schemas and applies them to reflections having the same + // name, if those reflections don't have a schema comment of their own. + const origConvertSymbol = app.converter.convertSymbol + app.converter.convertSymbol = (context, symbol, exportSymbol) => { + if (symbol.valueDeclaration) { + const sourceFile = symbol.valueDeclaration?.getSourceFile() + // find block comments + const blockCommentMatch = sourceFile.text.matchAll( + /\/\*[\s\S]*?\*\/|([^\\:]|^)\/\/.*$/gm + ) + for (const blockMatch of blockCommentMatch) { + blockMatch.forEach((matched) => { + if (!matched) { + return + } + const schemaStartIndex = matched.indexOf("@schema") + if (schemaStartIndex === -1) { + return + } + // find end index + let schemaEndIndex = matched.indexOf(" * @", schemaStartIndex) + + if (schemaEndIndex === -1) { + schemaEndIndex = matched.length + } + + const schemaText = matched + .substring(schemaStartIndex, schemaEndIndex) + .replaceAll(" */", "") + .replaceAll("*/", "") + .replaceAll(" * ", "") + const { name: schemaName = "" } = + /@schema (?\w+)/.exec(schemaText)?.groups || {} + + if (!schemaName || definedSchemas.has(schemaName)) { + return + } + + // attempt to parse schema and save it + try { + const parsedSchema = parse( + schemaText.replace("@schema", "schema:") + ) as Schema + + definedSchemas.set(schemaName, parsedSchema) + } catch (e) { + // ignore errors as the schema may be malformed. + console.error(`Error parsing schema ${schemaName}: ${e}`) + } + }) + } + } + + return origConvertSymbol(context, symbol, exportSymbol) + } + + app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => { + for (const reflection of context.project.getReflectionsByKind( + ReflectionKind.All + )) { + let schema: Schema | undefined + let { comment } = reflection + const schemaTags = comment?.getTags(`@schema`) + + if (schemaTags?.length) { + schemaTags.forEach((part) => { + if (part.content.length) { + const schemaComment = prepareSchemaComment(part.content) + schema = parse(schemaComment) + } + }) + reflection.comment?.removeTags("@schema") + } else if (!comment) { + if (definedSchemas.has(reflection.name)) { + schema = definedSchemas.get(reflection.name) + comment = new Comment() + } else if ("type" in reflection && reflection.type) { + const reflectionType = reflection.type as SomeType + + if ( + "name" in reflectionType && + definedSchemas.has(reflectionType.name) + ) { + schema = definedSchemas.get(reflectionType.name) + comment = new Comment() + } + } + } + + if (schema) { + if (schema.description) { + comment?.summary.push({ + kind: "text", + text: schema.description, + }) + } + + if (reflection.kind === ReflectionKind.TypeAlias) { + comment?.modifierTags.add(`@interface`) + } + + addComments(schema, reflection) + + if (!reflection.comment && comment) { + reflection.comment = comment + } + } + } + }) +} + +function prepareSchemaComment(commentParts: CommentDisplayPart[]) { + let result = `schema: ` + commentParts.forEach((commentPart) => { + result += commentPart.text + }) + return result +} + +function addComments(schema: Schema, reflection: Reflection) { + if (!schema.properties) { + if (schema.allOf) { + schema.allOf.forEach((valueChild) => { + addComments(valueChild, reflection) + }) + } else if (schema.oneOf) { + schema.oneOf.forEach((valueChild) => { + addComments(valueChild, reflection) + }) + } + return + } + const children = + "type" in reflection + ? getTypeChildren(reflection.type as SomeType, reflection.project) + : "children" in reflection + ? (reflection.children as DeclarationReflection[]) + : [] + + Object.entries(schema.properties).forEach(([key, value]) => { + const childItem = + children.find((child) => child.name === key) || + reflection.getChildByName(key) + + if (childItem) { + if (!childItem.comment) { + const comment = new Comment() + comment.summary.push({ + kind: "text", + text: value.description || "", + }) + childItem.comment = comment + } + + if ( + value.default !== undefined && + "defaultValue" in childItem && + !childItem.defaultValue + ) { + childItem.defaultValue = value.default + } + + if (value["x-expandable"]) { + childItem.comment.modifierTags.add(`@expandable`) + } + + if (value["x-featureFlag"]) { + childItem.comment.blockTags.push( + new CommentTag(`@featureFlag`, [ + { + kind: `inline-tag`, + text: value["x-featureFlag"], + tag: `@featureFlag`, + }, + ]) + ) + } + + if (value.items) { + addComments(value.items, childItem) + } + + if (value.properties || value.allOf || value.oneOf) { + addComments(value, childItem) + } + } + }) +} diff --git a/docs-util/packages/typedoc-plugin-modules/src/resolve-references-plugin.ts b/docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts similarity index 100% rename from docs-util/packages/typedoc-plugin-modules/src/resolve-references-plugin.ts rename to docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts diff --git a/docs-util/packages/typedoc-plugin-frontmatter/tsconfig.json b/docs-util/packages/typedoc-plugin-custom/tsconfig.json similarity index 100% rename from docs-util/packages/typedoc-plugin-frontmatter/tsconfig.json rename to docs-util/packages/typedoc-plugin-custom/tsconfig.json diff --git a/docs-util/packages/typedoc-plugin-frontmatter/README.md b/docs-util/packages/typedoc-plugin-frontmatter/README.md deleted file mode 100644 index 1edd40f93c..0000000000 --- a/docs-util/packages/typedoc-plugin-frontmatter/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# typedoc-plugin-frontmatter - -A Typedoc plugin that allows inserting frontmatter key-value pairs at the top of the exported Markdown files. - -> For more flexibility in what pages to apply the frontmatter data to, for example, to specify different frontmatter for different pages, ues the [`typedoc-plugin-markdown-medusa` plugin's `frontmatterData` option](../typedoc-plugin-markdown-medusa/README.md#configurations) - -## Configurations - -The following options are optional and can be used to customize the configurations of the plugin. - -### frontmatterData - -`frontmatterData` is an object of key-value pairs. If none provided, no frontmatter variables will be added to the Markdown files. - -An example of passing it in a JavaScript configuration file: - -```js -frontmatterData: { - displayed_sidebar: "jsClientSidebar", -}, -``` - -If passing the option in the command line the value should be a JSON object. - -### pagesPattern - -`pagesPattern` is a string that contains a regular expression. This allows you to limit the pages the frontmatter variables should be added to. - -By default, the frontmatter variables will be added to all files. - -An example of passing it in a JavaScript configuration file: - -```js -frontmatterData: { - pagesPattern: "internal\\.", -}, -``` - -## Build the Plugin - -Before using any command that makes use of this plugin, make sure to run the `build` command: - -```bash -yarn build -``` diff --git a/docs-util/packages/typedoc-plugin-frontmatter/package.json b/docs-util/packages/typedoc-plugin-frontmatter/package.json deleted file mode 100644 index b2523badf0..0000000000 --- a/docs-util/packages/typedoc-plugin-frontmatter/package.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "name": "typedoc-plugin-frontmatter", - "private": true, - "license": "MIT", - "publishConfig": { - "access": "public" - }, - "version": "0.0.0", - "description": "Plugin to add frontmatter key-values at the top of pages", - "main": "./dist/index.js", - "exports": "./dist/index.js", - "files": [ - "dist" - ], - "author": "Shahed Nasser", - "scripts": { - "build": "tsc", - "watch": "tsc --watch", - "lint": "eslint --ext .ts src" - }, - "peerDependencies": { - "typedoc": "0.25.x" - }, - "devDependencies": { - "@types/node": "^16.11.10", - "typescript": "^4.6" - }, - "keywords": [ - "typedocplugin", - "packages", - "monorepo", - "typedoc" - ], - "dependencies": { - "yaml": "^2.3.2" - } -} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/README.md b/docs-util/packages/typedoc-plugin-markdown-medusa/README.md index f2320dfcaa..9d8fc53973 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/README.md +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/README.md @@ -23,6 +23,7 @@ Aside from the options detailed in [typedoc-plugin-markdown](https://github.com/ - `frontmatterData`: (optional) an object that will be injected as frontmatter to the pages matching specified pattern. - `parameterComponent`: (optional) a string indicating the name of a React component to pass the parameters as an object to. This is only used if the `parameterStyle` option is set to `component`. This also must be used with the `mdxOutput` option enabled, and an import string for the component passed to the `mdxImports` option. The React component will receive a `parameters` prop, which is an array of type [Parameter](./src/types.ts#L95). - `mdxImports`: (optional) an array of strings, each holding an import statement that will be added to the beginning of each page. For example, `["import ParameterTypes from "@site/src/components/ParameterTypes""]`. Must be used along with the `mdxOutput` option enabled. + - `maxLevel`: (optional) a number indicating the maximum level parameters and return types are expanded. Default is `3`. ## Build Plugin diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/package.json b/docs-util/packages/typedoc-plugin-markdown-medusa/package.json index 9644f95d91..defa19f8f2 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/package.json +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/package.json @@ -23,7 +23,8 @@ "devDependencies": { "@types/node": "^16.11.10", "copyfiles": "^2.4.1", - "typescript": "^4.6" + "typescript": "^4.6", + "utils": "*" }, "keywords": [ "typedocplugin", diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/index.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/index.ts index 849986bf8c..8f3c431ead 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/index.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/index.ts @@ -109,5 +109,12 @@ export function load(app: Application) { type: ParameterType.Boolean, defaultValue: false, }) + + app.options.addDeclaration({ + help: "[Markdown Plugin] The maximum level to expand when retrieving reflection types.", + name: "maxLevel", + type: ParameterType.Number, + defaultValue: 3, + }) } export { MarkdownTheme } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts index 71ac109023..615f6db13f 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts @@ -43,6 +43,8 @@ import typeParameterComponentHelper from "./resources/helpers/type-parameter-com import showPropertiesAsComponentHelper from "./resources/helpers/show-properties-as-component" import commentTagHelper from "./resources/helpers/comment-tag" import exampleHelper from "./resources/helpers/example" +import ifFeatureFlagHelper from "./resources/helpers/if-feature-flag" +import featureFlagHelper from "./resources/helpers/feature-flag" import { MarkdownTheme } from "./theme" // test @@ -116,4 +118,6 @@ export function registerHelpers(theme: MarkdownTheme) { showPropertiesAsComponentHelper(theme) commentTagHelper(theme) exampleHelper() + ifFeatureFlagHelper() + featureFlagHelper() } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts index 2fc39eb206..9bceb4edfc 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/comments.ts @@ -1,6 +1,8 @@ import * as Handlebars from "handlebars" import { Comment } from "typedoc" +const EXCLUDED_TAGS = ["@returns", "@example", "@featureFlag"] + export default function () { Handlebars.registerHelper( "comments", @@ -18,9 +20,9 @@ export default function () { } if (showTags && comment.blockTags?.length) { - const filteredTags = comment.blockTags - .filter((tag) => tag.tag !== "@returns") - .filter((tag) => tag.tag !== "@example") + const filteredTags = comment.blockTags.filter( + (tag) => !EXCLUDED_TAGS.includes(tag.tag) + ) const tags = filteredTags.map((tag) => { return Handlebars.helpers.commentTag( tag, diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/feature-flag.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/feature-flag.ts new file mode 100644 index 0000000000..6b9e030938 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/feature-flag.ts @@ -0,0 +1,21 @@ +import * as Handlebars from "handlebars" +import { Comment } from "typedoc" + +export default function () { + Handlebars.registerHelper( + "featureFlag", + function (comment: Comment | undefined) { + if (!comment) { + return undefined + } + const featureFlagTag = comment.getTag("@featureFlag") + if (!featureFlagTag) { + return undefined + } + + return featureFlagTag.content + .map((tagContent) => tagContent.text) + .join("") + } + ) +} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-feature-flag.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-feature-flag.ts new file mode 100644 index 0000000000..12418b3348 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-feature-flag.ts @@ -0,0 +1,13 @@ +import * as Handlebars from "handlebars" +import { Reflection } from "typedoc" + +export default function () { + Handlebars.registerHelper( + "ifFeatureFlag", + function (this: Reflection, options: Handlebars.HelperOptions) { + return this.comment?.getTag("@featureFlag") !== undefined + ? options.fn(this) + : options.inverse(this) + } + ) +} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/feature-flag.hbs b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/feature-flag.hbs new file mode 100644 index 0000000000..0f961f69f9 --- /dev/null +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/feature-flag.hbs @@ -0,0 +1,13 @@ +{{#with model}} + +{{#ifFeatureFlag}} + +:::note + +To use this resource, make sure to [enable its feature flag: {{{featureFlag comment}}}](https://docs.medusajs.com/development/feature-flags/toggle) + +::: + +{{/ifFeatureFlag}} + +{{/with}} \ No newline at end of file diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/title.hbs b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/title.hbs index b321539d69..75f8b214de 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/title.hbs +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/title.hbs @@ -4,6 +4,8 @@ {{/ifShowPageTitle}} +{{> feature-flag}} + {{#with model}} {{{reflectionDescription}}} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts index 38fdf250cd..847b7154ee 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts @@ -56,6 +56,8 @@ export class MarkdownTheme extends Theme { static URL_PREFIX = /^(http|ftp)s?:\/\// + static MAX_LEVEL = 3 + constructor(renderer: Renderer) { super(renderer) @@ -85,6 +87,7 @@ export class MarkdownTheme extends Theme { "formatting" ) as FormattingOptionsType this.mdxOutput = this.getOption("mdxOutput") as boolean + MarkdownTheme.MAX_LEVEL = this.getOption("maxLevel") as number this.listenTo(this.owner, { [RendererEvent.BEGIN]: this.onBeginRenderer, diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts index 4fd7a4b6d2..f7d48876df 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts @@ -74,6 +74,7 @@ export type FormattingOptionType = { frontmatterData?: Record parameterComponent?: string mdxImports?: string[] + maxLevel?: number } export type FormattingOptionsType = { @@ -98,6 +99,8 @@ export type Parameter = { optional?: boolean defaultValue?: string description?: string + featureFlag?: string + expandable: boolean children?: Parameter[] } diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils.ts index 2b5fc33c76..32f0bc1594 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils.ts @@ -64,6 +64,10 @@ export function stripLineBreaks(str: string) { : "" } +export function stripCode(str: string) { + return stripLineBreaks(str.replace("```ts", "").replace("```", "")) +} + export function camelToTitleCase(text: string) { return ( text.substring(0, 1).toUpperCase() + diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts index 6ebca4a387..70c0e69079 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts @@ -1,17 +1,21 @@ -import { - Comment, - DeclarationReflection, - ReflectionKind, - ProjectReflection, - ReflectionType, - SomeType, -} from "typedoc" +import { Comment, ReflectionKind, ReflectionType } from "typedoc" import * as Handlebars from "handlebars" -import { stripLineBreaks } from "../utils" +import { stripCode, stripLineBreaks } from "../utils" import { Parameter, ParameterStyle, ReflectionParameterType } from "../types" import getType, { getReflectionType } from "./type-utils" +import { getTypeChildren } from "utils" +import { MarkdownTheme } from "../theme" -const MAX_LEVEL = 3 +const ALLOWED_KINDS: ReflectionKind[] = [ + ReflectionKind.EnumMember, + ReflectionKind.TypeParameter, + ReflectionKind.Property, + ReflectionKind.Parameter, + ReflectionKind.TypeAlias, + ReflectionKind.TypeLiteral, + ReflectionKind.Variable, + ReflectionKind.Reference, +] export default function reflectionFormatter( reflection: ReflectionParameterType, @@ -57,7 +61,10 @@ export function reflectionListFormatter( const hasChildren = "children" in reflection && reflection.children?.length - if ((reflection.type || hasChildren) && level + 1 <= MAX_LEVEL) { + if ( + (reflection.type || hasChildren) && + level + 1 <= MarkdownTheme.MAX_LEVEL + ) { const children = hasChildren ? reflection.children : getTypeChildren(reflection.type!, reflection.project) @@ -94,24 +101,32 @@ export function reflectionComponentFormatter( ? getType(reflection.type, "object") : getReflectionType(reflection, "object"), description: comments - ? stripLineBreaks(Handlebars.helpers.comments(comments)) + ? stripLineBreaks(Handlebars.helpers.comments(comments, true, false)) : "", optional, defaultValue, + expandable: reflection.comment?.hasModifier(`@expandable`) || false, + featureFlag: Handlebars.helpers.featureFlag(reflection.comment), children: [], } const hasChildren = "children" in reflection && reflection.children?.length - if ((reflection.type || hasChildren) && level + 1 <= MAX_LEVEL) { + if ( + (reflection.type || hasChildren) && + level + 1 <= MarkdownTheme.MAX_LEVEL + ) { const children = hasChildren ? reflection.children : getTypeChildren(reflection.type!, reflection.project) - children?.forEach((childItem) => { - componentItem.children?.push( - reflectionComponentFormatter(childItem, level + 1) - ) - }) + + children + ?.filter((childItem) => childItem.kindOf(ALLOWED_KINDS)) + .forEach((childItem) => { + componentItem.children?.push( + reflectionComponentFormatter(childItem, level + 1) + ) + }) } return componentItem @@ -195,11 +210,17 @@ export function getTableHeaders( export function getDefaultValue( parameter: ReflectionParameterType ): string | null { - if (!("defaultValue" in parameter)) { + const defaultComment = parameter.comment?.getTag(`@defaultValue`) + if (!("defaultValue" in parameter) && !defaultComment) { return null } - return parameter.defaultValue && parameter.defaultValue !== "..." - ? `\`${parameter.defaultValue}\`` + + return "defaultValue" in parameter && + parameter.defaultValue !== undefined && + parameter.defaultValue !== "..." + ? `${parameter.defaultValue}` + : defaultComment + ? defaultComment.content.map((content) => stripCode(content.text)).join() : null } @@ -246,28 +267,3 @@ function getItemExpandText( return "It accepts the following properties" } } - -export function getTypeChildren( - reflectionType: SomeType, - project: ProjectReflection -) { - let children: DeclarationReflection[] = [] - - switch (reflectionType.type) { - case "reference": - // eslint-disable-next-line no-case-declarations - const referencedReflection = project?.getChildByName(reflectionType.name) - - if ( - referencedReflection instanceof DeclarationReflection && - referencedReflection.children - ) { - children = referencedReflection.children - } - break - case "array": - children = getTypeChildren(reflectionType.elementType, project) - } - - return children -} diff --git a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/return-reflection-formatter.ts b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/return-reflection-formatter.ts index 5114f3d91c..1693a1f5fc 100644 --- a/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/return-reflection-formatter.ts +++ b/docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/return-reflection-formatter.ts @@ -12,8 +12,7 @@ import { getDefaultValue, reflectionComponentFormatter, } from "./reflection-formatter" - -const MAX_LEVEL = 3 +import { MarkdownTheme } from "../theme" export function returnReflectionComponentFormatter( reflectionType: SomeType, @@ -41,9 +40,14 @@ export function returnReflectionComponentFormatter( ) || "" : "", description: comment ? getReturnComment(comment) : "", + expandable: comment?.hasModifier(`@expandable`) || false, + featureFlag: Handlebars.helpers.featureFlag(comment), children: [], }) - if (!isOnlyVoid(reflectionType.typeArguments) && level + 1 <= MAX_LEVEL) { + if ( + !isOnlyVoid(reflectionType.typeArguments) && + level + 1 <= MarkdownTheme.MAX_LEVEL + ) { reflectionType.typeArguments.forEach((typeArg) => { const typeArgComponent = returnReflectionComponentFormatter( typeArg, @@ -95,9 +99,11 @@ export function returnReflectionComponentFormatter( ) || "" : "", description: comment ? getReturnComment(comment) : "", + expandable: comment?.hasModifier(`@expandable`) || false, + featureFlag: Handlebars.helpers.featureFlag(comment), children: [], }) - if (level + 1 <= MAX_LEVEL) { + if (level + 1 <= MarkdownTheme.MAX_LEVEL) { const elementTypeItem = returnReflectionComponentFormatter( reflectionType.elementType, project, @@ -126,13 +132,15 @@ export function returnReflectionComponentFormatter( ) || "" : "", description: comment ? getReturnComment(comment) : "", + expandable: comment?.hasModifier(`@expandable`) || false, + featureFlag: Handlebars.helpers.featureFlag(comment), children: [], }) pushTo = componentItem[parentKey - 1].children! } else { pushTo = componentItem } - if (level + 1 <= MAX_LEVEL) { + if (level + 1 <= MarkdownTheme.MAX_LEVEL) { reflectionType.elements.forEach((element) => { const elementTypeItem = returnReflectionComponentFormatter( element, @@ -159,6 +167,8 @@ export function returnReflectionComponentFormatter( ? getDefaultValue(reflectionType.declaration) || "" : "", description: comment ? getReturnComment(comment) : "", + expandable: comment?.hasModifier(`@expandable`) || false, + featureFlag: Handlebars.helpers.featureFlag(comment), children: [], }) } diff --git a/docs-util/packages/typedoc-plugin-modules/.gitignore b/docs-util/packages/typedoc-plugin-modules/.gitignore deleted file mode 100644 index 13b6b556eb..0000000000 --- a/docs-util/packages/typedoc-plugin-modules/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -dist -.yarn \ No newline at end of file diff --git a/docs-util/packages/typedoc-plugin-modules/README.md b/docs-util/packages/typedoc-plugin-modules/README.md deleted file mode 100644 index b70e65dacb..0000000000 --- a/docs-util/packages/typedoc-plugin-modules/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# typedoc-plugin-modules - -A Typedoc plugin that includes helper plugins for documenting modules. The `resolve-reference-plugin` imitates the [`typedoc-plugin-missing-exports`](https://www.npmjs.com/package/typedoc-plugin-missing-exports) plugin. - -## Configurations - -Accepts the same options as the [`typedoc-plugin-missing-exports`](https://www.npmjs.com/package/typedoc-plugin-missing-exports) plugin. - -## Build the Plugin - -Before using any command that makes use of this plugin, make sure to run the `build` command: - -```bash -yarn build -``` diff --git a/docs-util/packages/typedoc-plugin-modules/src/index.ts b/docs-util/packages/typedoc-plugin-modules/src/index.ts deleted file mode 100644 index 805bbf705f..0000000000 --- a/docs-util/packages/typedoc-plugin-modules/src/index.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { Application } from "typedoc" -import { load as resolveReferencesPluginLoad } from "./resolve-references-plugin" - -export function load(app: Application) { - resolveReferencesPluginLoad(app) -} diff --git a/docs-util/packages/utils/package.json b/docs-util/packages/utils/package.json new file mode 100644 index 0000000000..087a41d26a --- /dev/null +++ b/docs-util/packages/utils/package.json @@ -0,0 +1,26 @@ +{ + "name": "utils", + "private": true, + "license": "MIT", + "publishConfig": { + "access": "public" + }, + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "version": "0.0.0", + "scripts": { + "build": "yarn clean && tsc", + "lint": "eslint --ext .ts src", + "clean": "rimraf dist" + }, + "peerDependencies": { + "typedoc": "0.25.x" + }, + "devDependencies": { + "@types/node": "^16.11.10", + "typescript": "^4.6" + }, + "dependencies": { + "rimraf": "^5.0.5" + } +} diff --git a/docs-util/packages/utils/src/get-project-child.ts b/docs-util/packages/utils/src/get-project-child.ts new file mode 100644 index 0000000000..d1a36352b5 --- /dev/null +++ b/docs-util/packages/utils/src/get-project-child.ts @@ -0,0 +1,43 @@ +import { + DeclarationReflection, + ProjectReflection, + ReflectionKind, +} from "typedoc" + +export function getProjectChild( + project: ProjectReflection, + childName: string +): DeclarationReflection | undefined { + let reflection: DeclarationReflection | undefined = project.getChildByName( + childName + ) as DeclarationReflection + const splitChildName = childName.split(".") + + if (!reflection && splitChildName.length > 1) { + reflection = getProjectChild( + project, + splitChildName[splitChildName.length - 1] + ) + } + + if ( + !reflection && + project.parent && + project.parent instanceof ProjectReflection + ) { + reflection = getProjectChild(project.parent, childName) + } + + if (!reflection) { + const modules = project.getChildrenByKind(ReflectionKind.Module) + for (const module of modules) { + reflection = module.getChildByName(childName) as DeclarationReflection + + if (reflection) { + break + } + } + } + + return reflection +} diff --git a/docs-util/packages/utils/src/get-type-children.ts b/docs-util/packages/utils/src/get-type-children.ts new file mode 100644 index 0000000000..bfe4b143f7 --- /dev/null +++ b/docs-util/packages/utils/src/get-type-children.ts @@ -0,0 +1,76 @@ +import { DeclarationReflection, ProjectReflection, SomeType } from "typedoc" +import { getProjectChild } from "./get-project-child" + +export function getTypeChildren( + reflectionType: SomeType, + project: ProjectReflection | undefined +): DeclarationReflection[] { + let children: DeclarationReflection[] = [] + + switch (reflectionType.type) { + case "intersection": + reflectionType.types.forEach((intersectionType) => { + children.push(...getTypeChildren(intersectionType, project)) + }) + break + case "reference": + // eslint-disable-next-line no-case-declarations + const referencedReflection = + reflectionType.reflection && "children" in reflectionType.reflection + ? reflectionType.reflection + : project + ? getProjectChild(project, reflectionType.name) + : undefined + + if (referencedReflection instanceof DeclarationReflection) { + if (referencedReflection.children) { + children = referencedReflection.children + } else if (reflectionType.typeArguments?.length) { + reflectionType.typeArguments.forEach((typeArgument, index) => { + if (reflectionType.name === "Omit" && index > 0) { + switch (typeArgument.type) { + case "literal": + removeChild(typeArgument.value?.toString(), children) + break + case "union": + typeArgument.types.forEach((childItem) => { + if (childItem.type === "literal") { + removeChild(childItem.value?.toString(), children) + } else { + getTypeChildren(childItem, project).forEach((child) => { + removeChild(child.name, children) + }) + } + }) + } + } else { + const typeArgumentChildren = getTypeChildren( + typeArgument, + project + ) + children.push(...typeArgumentChildren) + } + }) + } else if (referencedReflection.type) { + children = getTypeChildren(referencedReflection.type, project) + } + } + break + case "reflection": + children = reflectionType.declaration.children || [ + reflectionType.declaration, + ] + break + case "array": + children = getTypeChildren(reflectionType.elementType, project) + } + + return children +} + +function removeChild(name: unknown, children: DeclarationReflection[]) { + const childIndex = children.findIndex((child) => child.name === name) + if (childIndex !== -1) { + children.splice(childIndex, 1) + } +} diff --git a/docs-util/packages/utils/src/index.ts b/docs-util/packages/utils/src/index.ts new file mode 100644 index 0000000000..da5d78440f --- /dev/null +++ b/docs-util/packages/utils/src/index.ts @@ -0,0 +1,2 @@ +export * from "./get-type-children" +export * from "./get-project-child" diff --git a/docs-util/packages/typedoc-plugin-modules/tsconfig.json b/docs-util/packages/utils/tsconfig.json similarity index 50% rename from docs-util/packages/typedoc-plugin-modules/tsconfig.json rename to docs-util/packages/utils/tsconfig.json index b3b4792cd9..af3efb5bc3 100644 --- a/docs-util/packages/typedoc-plugin-modules/tsconfig.json +++ b/docs-util/packages/utils/tsconfig.json @@ -2,7 +2,10 @@ "extends": "../../tsconfig", "compilerOptions": { "outDir": "./dist", - "rootDir": "./src" + "rootDir": "./src", + "declaration": true, + "declarationMap": true, + "esModuleInterop": true }, "include": ["src"] } \ No newline at end of file diff --git a/docs-util/yarn.lock b/docs-util/yarn.lock index a2b0bf9f36..ec72c90d90 100644 --- a/docs-util/yarn.lock +++ b/docs-util/yarn.lock @@ -325,6 +325,23 @@ __metadata: languageName: node linkType: hard +"@eslint/eslintrc@npm:^2.1.3": + version: 2.1.3 + resolution: "@eslint/eslintrc@npm:2.1.3" + dependencies: + ajv: ^6.12.4 + debug: ^4.3.2 + espree: ^9.6.0 + globals: ^13.19.0 + ignore: ^5.2.0 + import-fresh: ^3.2.1 + js-yaml: ^4.1.0 + minimatch: ^3.1.2 + strip-json-comments: ^3.1.1 + checksum: f4103f4346126292eb15581c5a1d12bef03410fd3719dedbdb92e1f7031d46a5a2d60de8566790445d5d4b70b75ba050876799a11f5fff8265a91ee3fa77dab0 + languageName: node + linkType: hard + "@eslint/js@npm:8.50.0": version: 8.50.0 resolution: "@eslint/js@npm:8.50.0" @@ -332,6 +349,13 @@ __metadata: languageName: node linkType: hard +"@eslint/js@npm:8.53.0": + version: 8.53.0 + resolution: "@eslint/js@npm:8.53.0" + checksum: d29f6c207b2f6dc4ef174d16a3c07b0d3a17ca3d805680496ff267edd773e3bac41db4e7dcab622ca1970d892535bd19671e2a756d4eac75e96fd8c8dcdb619b + languageName: node + linkType: hard + "@fastify/busboy@npm:^2.0.0": version: 2.0.0 resolution: "@fastify/busboy@npm:2.0.0" @@ -359,6 +383,17 @@ __metadata: languageName: node linkType: hard +"@humanwhocodes/config-array@npm:^0.11.13": + version: 0.11.13 + resolution: "@humanwhocodes/config-array@npm:0.11.13" + dependencies: + "@humanwhocodes/object-schema": ^2.0.1 + debug: ^4.1.1 + minimatch: ^3.0.5 + checksum: d76ca802d853366094d0e98ff0d0994117fc8eff96649cd357b15e469e428228f597cd2e929d54ab089051684949955f16ee905bb19f7b2f0446fb377157be7a + languageName: node + linkType: hard + "@humanwhocodes/module-importer@npm:^1.0.1": version: 1.0.1 resolution: "@humanwhocodes/module-importer@npm:1.0.1" @@ -373,6 +408,13 @@ __metadata: languageName: node linkType: hard +"@humanwhocodes/object-schema@npm:^2.0.1": + version: 2.0.1 + resolution: "@humanwhocodes/object-schema@npm:2.0.1" + checksum: 9dba24e59fdb4041829d92b693aacb778add3b6f612aaa9c0774f3b650c11a378cc64f042a59da85c11dae33df456580a3c36837b953541aed6ff94294f97fac + languageName: node + linkType: hard + "@isaacs/cliui@npm:^8.0.2": version: 8.0.2 resolution: "@isaacs/cliui@npm:8.0.2" @@ -777,6 +819,13 @@ __metadata: languageName: node linkType: hard +"@ungap/structured-clone@npm:^1.2.0": + version: 1.2.0 + resolution: "@ungap/structured-clone@npm:1.2.0" + checksum: 8209c937cb39119f44eb63cf90c0b73e7c754209a6411c707be08e50e29ee81356dca1a848a405c8bdeebfe2f5e4f831ad310ae1689eeef65e7445c090c6657d + languageName: node + linkType: hard + "acorn-jsx@npm:^5.3.2": version: 5.3.2 resolution: "acorn-jsx@npm:5.3.2" @@ -1360,6 +1409,54 @@ __metadata: languageName: node linkType: hard +"eslint@npm:^8.53.0": + version: 8.53.0 + resolution: "eslint@npm:8.53.0" + dependencies: + "@eslint-community/eslint-utils": ^4.2.0 + "@eslint-community/regexpp": ^4.6.1 + "@eslint/eslintrc": ^2.1.3 + "@eslint/js": 8.53.0 + "@humanwhocodes/config-array": ^0.11.13 + "@humanwhocodes/module-importer": ^1.0.1 + "@nodelib/fs.walk": ^1.2.8 + "@ungap/structured-clone": ^1.2.0 + ajv: ^6.12.4 + chalk: ^4.0.0 + cross-spawn: ^7.0.2 + debug: ^4.3.2 + doctrine: ^3.0.0 + escape-string-regexp: ^4.0.0 + eslint-scope: ^7.2.2 + eslint-visitor-keys: ^3.4.3 + espree: ^9.6.1 + esquery: ^1.4.2 + esutils: ^2.0.2 + fast-deep-equal: ^3.1.3 + file-entry-cache: ^6.0.1 + find-up: ^5.0.0 + glob-parent: ^6.0.2 + globals: ^13.19.0 + graphemer: ^1.4.0 + ignore: ^5.2.0 + imurmurhash: ^0.1.4 + is-glob: ^4.0.0 + is-path-inside: ^3.0.3 + js-yaml: ^4.1.0 + json-stable-stringify-without-jsonify: ^1.0.1 + levn: ^0.4.1 + lodash.merge: ^4.6.2 + minimatch: ^3.1.2 + natural-compare: ^1.4.0 + optionator: ^0.9.3 + strip-ansi: ^6.0.1 + text-table: ^0.2.0 + bin: + eslint: bin/eslint.js + checksum: c5cd0049488c0463dab7d97466767ca5a1d0b3b59d0a223122683dc8039ecea30b27867fb9e38906b4c1ab9d09ece8a802a6c540d8905016f1cc4b4bb27329af + languageName: node + linkType: hard + "espree@npm:^9.6.0, espree@npm:^9.6.1": version: 9.6.1 resolution: "espree@npm:9.6.1" @@ -1596,7 +1693,7 @@ __metadata: languageName: node linkType: hard -"glob@npm:^10.3.10": +"glob@npm:^10.3.10, glob@npm:^10.3.7": version: 10.3.10 resolution: "glob@npm:10.3.10" dependencies: @@ -2443,6 +2540,17 @@ __metadata: languageName: node linkType: hard +"rimraf@npm:^5.0.5": + version: 5.0.5 + resolution: "rimraf@npm:5.0.5" + dependencies: + glob: ^10.3.7 + bin: + rimraf: dist/esm/bin.mjs + checksum: d50dbe724f33835decd88395b25ed35995077c60a50ae78ded06e0185418914e555817aad1b4243edbff2254548c2f6ad6f70cc850040bebb4da9e8cc016f586 + languageName: node + linkType: hard + "run-applescript@npm:^5.0.0": version: 5.0.0 resolution: "run-applescript@npm:5.0.0" @@ -2484,12 +2592,12 @@ __metadata: typedoc: 0.25.1 typedoc-config: "*" typedoc-monorepo-link-types: ^0.0.2 + typedoc-plugin-custom: "*" typedoc-plugin-frontmatter: "*" typedoc-plugin-markdown: 3.16.0 typedoc-plugin-markdown-medusa: "*" typedoc-plugin-merge-modules: 5.1.0 typedoc-plugin-missing-exports: ^2.1.0 - typedoc-plugin-modules: "*" typedoc-plugin-reference-excluder: 1.1.3 typedoc-plugin-rename-defaults: ^0.6.6 typescript: ^5.2.2 @@ -2875,6 +2983,8 @@ __metadata: "typedoc-config@*, typedoc-config@workspace:packages/typedoc-config": version: 0.0.0-use.local resolution: "typedoc-config@workspace:packages/typedoc-config" + peerDependencies: + typedoc: 0.25.x languageName: unknown linkType: soft @@ -2887,18 +2997,31 @@ __metadata: languageName: node linkType: hard -"typedoc-plugin-frontmatter@*, typedoc-plugin-frontmatter@workspace:packages/typedoc-plugin-frontmatter": +"typedoc-plugin-custom@*, typedoc-plugin-custom@workspace:packages/typedoc-plugin-custom": version: 0.0.0-use.local - resolution: "typedoc-plugin-frontmatter@workspace:packages/typedoc-plugin-frontmatter" + resolution: "typedoc-plugin-custom@workspace:packages/typedoc-plugin-custom" dependencies: "@types/node": ^16.11.10 + eslint: ^8.53.0 + glob: ^10.3.10 + typedoc-plugin-markdown: ^3.16.0 typescript: ^4.6 - yaml: ^2.3.2 + utils: "*" + yaml: ^2.3.3 peerDependencies: typedoc: 0.25.x languageName: unknown linkType: soft +"typedoc-plugin-frontmatter@npm:*": + version: 0.0.2 + resolution: "typedoc-plugin-frontmatter@npm:0.0.2" + dependencies: + yaml: ^2.2.2 + checksum: bd14645bf613dc58828c69004e53ce141a448e137a3deb5f8994a105d484c9b118731ed5ae3907541dda6cc034b30ab6e665b5d7b16cb9eb222df1c871d2fb21 + languageName: node + linkType: hard + "typedoc-plugin-markdown-medusa@*, typedoc-plugin-markdown-medusa@workspace:packages/typedoc-plugin-markdown-medusa": version: 0.0.0-use.local resolution: "typedoc-plugin-markdown-medusa@workspace:packages/typedoc-plugin-markdown-medusa" @@ -2907,6 +3030,7 @@ __metadata: copyfiles: ^2.4.1 handlebars: ^4.7.8 typescript: ^4.6 + utils: "*" peerDependencies: typedoc: 0.25.x languageName: unknown @@ -2941,19 +3065,6 @@ __metadata: languageName: node linkType: hard -"typedoc-plugin-modules@*, typedoc-plugin-modules@workspace:packages/typedoc-plugin-modules": - version: 0.0.0-use.local - resolution: "typedoc-plugin-modules@workspace:packages/typedoc-plugin-modules" - dependencies: - "@types/node": ^16.11.10 - glob: ^10.3.10 - typedoc-plugin-markdown: ^3.16.0 - typescript: ^4.6 - peerDependencies: - typedoc: 0.25.x - languageName: unknown - linkType: soft - "typedoc-plugin-reference-excluder@npm:1.1.3": version: 1.1.3 resolution: "typedoc-plugin-reference-excluder@npm:1.1.3" @@ -3097,6 +3208,18 @@ __metadata: languageName: node linkType: hard +"utils@*, utils@workspace:packages/utils": + version: 0.0.0-use.local + resolution: "utils@workspace:packages/utils" + dependencies: + "@types/node": ^16.11.10 + rimraf: ^5.0.5 + typescript: ^4.6 + peerDependencies: + typedoc: 0.25.x + languageName: unknown + linkType: soft + "uuid@npm:^8.3.2": version: 8.3.2 resolution: "uuid@npm:8.3.2" @@ -3219,10 +3342,10 @@ __metadata: languageName: node linkType: hard -"yaml@npm:^2.3.2": - version: 2.3.2 - resolution: "yaml@npm:2.3.2" - checksum: c2aac464015f037911c5b819475e81e52119e5495e3d43fe7cb82b5a84d59d66a86049dc85d8e90658636c1c04dde177ae196818deaf76c1bda4d34209d5c087 +"yaml@npm:^2.2.2, yaml@npm:^2.3.3": + version: 2.3.3 + resolution: "yaml@npm:2.3.3" + checksum: a0c56bf682159b0567e9cbbddf23efc2f6806f6450716d9be6ec5eb1af1b941e95c8d3dc9c47da20d1b6883a9d6c61e31cf98bb4b77ebca4396bf772657f2f00 languageName: node linkType: hard diff --git a/packages/generated/client-types/src/lib/models/AddressPayload.ts b/packages/generated/client-types/src/lib/models/AddressPayload.ts index cad0473d3f..7f1e628e14 100644 --- a/packages/generated/client-types/src/lib/models/AddressPayload.ts +++ b/packages/generated/client-types/src/lib/models/AddressPayload.ts @@ -19,6 +19,9 @@ export interface AddressPayload { * Phone Number */ phone?: string + /** + * Company + */ company?: string /** * Address line 1 diff --git a/packages/generated/client-types/src/lib/models/AdminAuthRes.ts b/packages/generated/client-types/src/lib/models/AdminAuthRes.ts index c0a61b4245..83120b7489 100644 --- a/packages/generated/client-types/src/lib/models/AdminAuthRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminAuthRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { User } from "./User" +/** + * The user's details. + */ export interface AdminAuthRes { /** * User details. diff --git a/packages/generated/client-types/src/lib/models/AdminBatchJobRes.ts b/packages/generated/client-types/src/lib/models/AdminBatchJobRes.ts index 5787752761..088f192e19 100644 --- a/packages/generated/client-types/src/lib/models/AdminBatchJobRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminBatchJobRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { BatchJob } from "./BatchJob" +/** + * The batch job's details. + */ export interface AdminBatchJobRes { /** * Batch job details. diff --git a/packages/generated/client-types/src/lib/models/AdminBearerAuthRes.ts b/packages/generated/client-types/src/lib/models/AdminBearerAuthRes.ts index fa81e2c7ba..e879ab7a57 100644 --- a/packages/generated/client-types/src/lib/models/AdminBearerAuthRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminBearerAuthRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The access token of the user, if they're authenticated successfully. + */ export interface AdminBearerAuthRes { /** * Access token that can be used to send authenticated requests. diff --git a/packages/generated/client-types/src/lib/models/AdminCollectionsRes.ts b/packages/generated/client-types/src/lib/models/AdminCollectionsRes.ts index 8888e1a9b9..7b8f5c1e52 100644 --- a/packages/generated/client-types/src/lib/models/AdminCollectionsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminCollectionsRes.ts @@ -5,6 +5,12 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCollection } from "./ProductCollection" +/** + * The collection's details. + */ export interface AdminCollectionsRes { + /** + * Product Collection details. + */ collection: SetRelation } diff --git a/packages/generated/client-types/src/lib/models/AdminCurrenciesListRes.ts b/packages/generated/client-types/src/lib/models/AdminCurrenciesListRes.ts index 6efe903f9b..55c5ee1c46 100644 --- a/packages/generated/client-types/src/lib/models/AdminCurrenciesListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminCurrenciesListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Currency } from "./Currency" +/** + * List of currencies with pagination fields. + */ export interface AdminCurrenciesListRes { /** * An array of currency details. diff --git a/packages/generated/client-types/src/lib/models/AdminCurrenciesRes.ts b/packages/generated/client-types/src/lib/models/AdminCurrenciesRes.ts index 00ac125a74..7360d1a6a3 100644 --- a/packages/generated/client-types/src/lib/models/AdminCurrenciesRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminCurrenciesRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Currency } from "./Currency" +/** + * A currency's details. + */ export interface AdminCurrenciesRes { /** * Currency details. diff --git a/packages/generated/client-types/src/lib/models/AdminCustomerGroupsRes.ts b/packages/generated/client-types/src/lib/models/AdminCustomerGroupsRes.ts index 309e4e711d..8ffca456d5 100644 --- a/packages/generated/client-types/src/lib/models/AdminCustomerGroupsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminCustomerGroupsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { CustomerGroup } from "./CustomerGroup" +/** + * The customer group's details. + */ export interface AdminCustomerGroupsRes { /** * Customer group details. diff --git a/packages/generated/client-types/src/lib/models/AdminCustomersListRes.ts b/packages/generated/client-types/src/lib/models/AdminCustomersListRes.ts index 191207e4eb..0b4adfb8a9 100644 --- a/packages/generated/client-types/src/lib/models/AdminCustomersListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminCustomersListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Customer } from "./Customer" +/** + * The list of customers with pagination fields. + */ export interface AdminCustomersListRes { /** * An array of customer details. diff --git a/packages/generated/client-types/src/lib/models/AdminCustomersRes.ts b/packages/generated/client-types/src/lib/models/AdminCustomersRes.ts index 0e0219e853..948530183f 100644 --- a/packages/generated/client-types/src/lib/models/AdminCustomersRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminCustomersRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Customer } from "./Customer" +/** + * The customer's details. + */ export interface AdminCustomersRes { /** * Customer details. diff --git a/packages/generated/client-types/src/lib/models/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.ts b/packages/generated/client-types/src/lib/models/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.ts index 0f30e23b8c..59f1123bfc 100644 --- a/packages/generated/client-types/src/lib/models/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminDeleteDiscountsDiscountConditionsConditionBatchReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The resources to remove. + */ export interface AdminDeleteDiscountsDiscountConditionsConditionBatchReq { /** * The resources to be removed from the discount condition diff --git a/packages/generated/client-types/src/lib/models/AdminDeleteProductsFromCollectionRes.ts b/packages/generated/client-types/src/lib/models/AdminDeleteProductsFromCollectionRes.ts index 025c5a46ac..1c13d6c44a 100644 --- a/packages/generated/client-types/src/lib/models/AdminDeleteProductsFromCollectionRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminDeleteProductsFromCollectionRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * Deletion operation details + */ export interface AdminDeleteProductsFromCollectionRes { /** * The ID of the collection diff --git a/packages/generated/client-types/src/lib/models/AdminDeleteTaxRatesTaxRateProductTypesReq.ts b/packages/generated/client-types/src/lib/models/AdminDeleteTaxRatesTaxRateProductTypesReq.ts index 43f862d7ce..bd68673cea 100644 --- a/packages/generated/client-types/src/lib/models/AdminDeleteTaxRatesTaxRateProductTypesReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminDeleteTaxRatesTaxRateProductTypesReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * Product types to remove from the tax rates. + */ export interface AdminDeleteTaxRatesTaxRateProductTypesReq { /** * The IDs of the product types to remove their association with this tax rate. diff --git a/packages/generated/client-types/src/lib/models/AdminDiscountsListRes.ts b/packages/generated/client-types/src/lib/models/AdminDiscountsListRes.ts index 041b6daaa5..5f621a358a 100644 --- a/packages/generated/client-types/src/lib/models/AdminDiscountsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminDiscountsListRes.ts @@ -6,7 +6,13 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Discount } from "./Discount" import type { DiscountRule } from "./DiscountRule" +/** + * The list of discounts with pagination fields. + */ export interface AdminDiscountsListRes { + /** + * The list of discounts. + */ discounts: Array< Merge< SetRelation, diff --git a/packages/generated/client-types/src/lib/models/AdminDiscountsRes.ts b/packages/generated/client-types/src/lib/models/AdminDiscountsRes.ts index d469dfc7ce..b4aac3465a 100644 --- a/packages/generated/client-types/src/lib/models/AdminDiscountsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminDiscountsRes.ts @@ -7,6 +7,9 @@ import type { Discount } from "./Discount" import type { DiscountRule } from "./DiscountRule" import type { Region } from "./Region" +/** + * The discount's details. + */ export interface AdminDiscountsRes { /** * Discount details. diff --git a/packages/generated/client-types/src/lib/models/AdminDraftOrdersListRes.ts b/packages/generated/client-types/src/lib/models/AdminDraftOrdersListRes.ts index d39c50f3f5..6639603195 100644 --- a/packages/generated/client-types/src/lib/models/AdminDraftOrdersListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminDraftOrdersListRes.ts @@ -7,6 +7,9 @@ import type { Cart } from "./Cart" import type { DraftOrder } from "./DraftOrder" import type { LineItem } from "./LineItem" +/** + * The list of draft orders with pagination fields. + */ export interface AdminDraftOrdersListRes { /** * An array of draft order's details. diff --git a/packages/generated/client-types/src/lib/models/AdminDraftOrdersRes.ts b/packages/generated/client-types/src/lib/models/AdminDraftOrdersRes.ts index 5524379835..7e99a1668b 100644 --- a/packages/generated/client-types/src/lib/models/AdminDraftOrdersRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminDraftOrdersRes.ts @@ -12,6 +12,9 @@ import type { ProductVariant } from "./ProductVariant" import type { Region } from "./Region" import type { ShippingMethod } from "./ShippingMethod" +/** + * The list of draft orders. + */ export interface AdminDraftOrdersRes { /** * Draft order's details. diff --git a/packages/generated/client-types/src/lib/models/AdminExtendedStoresRes.ts b/packages/generated/client-types/src/lib/models/AdminExtendedStoresRes.ts index c7e0dda843..3a881dc5ed 100644 --- a/packages/generated/client-types/src/lib/models/AdminExtendedStoresRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminExtendedStoresRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ExtendedStoreDTO } from "./ExtendedStoreDTO" +/** + * The store's details with additional details like payment and tax providers. + */ export interface AdminExtendedStoresRes { /** * Store details. diff --git a/packages/generated/client-types/src/lib/models/AdminGetRegionsRegionFulfillmentOptionsRes.ts b/packages/generated/client-types/src/lib/models/AdminGetRegionsRegionFulfillmentOptionsRes.ts index 582695c38a..3ec74dd991 100644 --- a/packages/generated/client-types/src/lib/models/AdminGetRegionsRegionFulfillmentOptionsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminGetRegionsRegionFulfillmentOptionsRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The list of fulfillment options in a region. + */ export interface AdminGetRegionsRegionFulfillmentOptionsRes { /** * Fulfillment providers details. diff --git a/packages/generated/client-types/src/lib/models/AdminGetVariantsVariantInventoryRes.ts b/packages/generated/client-types/src/lib/models/AdminGetVariantsVariantInventoryRes.ts index eba3d094e7..f77c1a255f 100644 --- a/packages/generated/client-types/src/lib/models/AdminGetVariantsVariantInventoryRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminGetVariantsVariantInventoryRes.ts @@ -5,9 +5,12 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { VariantInventory } from "./VariantInventory" +/** + * The variant's inventory details. + */ export interface AdminGetVariantsVariantInventoryRes { /** - * The product variant's. + * The product variant's inventory details. */ variant?: VariantInventory } diff --git a/packages/generated/client-types/src/lib/models/AdminGiftCardsListRes.ts b/packages/generated/client-types/src/lib/models/AdminGiftCardsListRes.ts index 964e17f9b2..08ee3d765d 100644 --- a/packages/generated/client-types/src/lib/models/AdminGiftCardsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminGiftCardsListRes.ts @@ -6,7 +6,13 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { GiftCard } from "./GiftCard" import type { Region } from "./Region" +/** + * The list of gift cards with pagination fields. + */ export interface AdminGiftCardsListRes { + /** + * The list of gift cards. + */ gift_cards: Array< Merge< SetRelation, diff --git a/packages/generated/client-types/src/lib/models/AdminGiftCardsRes.ts b/packages/generated/client-types/src/lib/models/AdminGiftCardsRes.ts index 5464dae1ab..81257777a5 100644 --- a/packages/generated/client-types/src/lib/models/AdminGiftCardsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminGiftCardsRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { GiftCard } from "./GiftCard" import type { Region } from "./Region" +/** + * The gift card's details. + */ export interface AdminGiftCardsRes { /** * A gift card's details. diff --git a/packages/generated/client-types/src/lib/models/AdminInventoryItemsLocationLevelsRes.ts b/packages/generated/client-types/src/lib/models/AdminInventoryItemsLocationLevelsRes.ts index b213f78294..63f401a08d 100644 --- a/packages/generated/client-types/src/lib/models/AdminInventoryItemsLocationLevelsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminInventoryItemsLocationLevelsRes.ts @@ -5,12 +5,18 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { InventoryLevelDTO } from "./InventoryLevelDTO" +/** + * Details of inventory items and their associated location levels. + */ export interface AdminInventoryItemsLocationLevelsRes { + /** + * An inventory item's ID and associated location levels. + */ inventory_item: { /** * The id of the location */ - id: any + id: string /** * List of stock levels at a given location */ diff --git a/packages/generated/client-types/src/lib/models/AdminInventoryItemsRes.ts b/packages/generated/client-types/src/lib/models/AdminInventoryItemsRes.ts index 6c42896ef9..681f0f70c5 100644 --- a/packages/generated/client-types/src/lib/models/AdminInventoryItemsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminInventoryItemsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { InventoryItemDTO } from "./InventoryItemDTO" +/** + * The inventory item's details. + */ export interface AdminInventoryItemsRes { /** * Inventory Item details diff --git a/packages/generated/client-types/src/lib/models/AdminListInvitesRes.ts b/packages/generated/client-types/src/lib/models/AdminListInvitesRes.ts index 35b501cd61..3d7a5f2861 100644 --- a/packages/generated/client-types/src/lib/models/AdminListInvitesRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminListInvitesRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Invite } from "./Invite" +/** + * The list of invites. + */ export interface AdminListInvitesRes { /** * An array of invites diff --git a/packages/generated/client-types/src/lib/models/AdminNotesListRes.ts b/packages/generated/client-types/src/lib/models/AdminNotesListRes.ts index 2591863464..7fc32a44a7 100644 --- a/packages/generated/client-types/src/lib/models/AdminNotesListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminNotesListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Note } from "./Note" +/** + * The list of notes with pagination fields. + */ export interface AdminNotesListRes { /** * An array of notes diff --git a/packages/generated/client-types/src/lib/models/AdminNotesRes.ts b/packages/generated/client-types/src/lib/models/AdminNotesRes.ts index 048644a86f..f72e5d1f48 100644 --- a/packages/generated/client-types/src/lib/models/AdminNotesRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminNotesRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Note } from "./Note" +/** + * The note's details. + */ export interface AdminNotesRes { /** * Note details. diff --git a/packages/generated/client-types/src/lib/models/AdminNotificationsRes.ts b/packages/generated/client-types/src/lib/models/AdminNotificationsRes.ts index c99ef6d83c..97f9474b77 100644 --- a/packages/generated/client-types/src/lib/models/AdminNotificationsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminNotificationsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Notification } from "./Notification" +/** + * The notification's details. + */ export interface AdminNotificationsRes { /** * Notification details diff --git a/packages/generated/client-types/src/lib/models/AdminOrderEditItemChangeDeleteRes.ts b/packages/generated/client-types/src/lib/models/AdminOrderEditItemChangeDeleteRes.ts index 68f1ea808c..faf396b903 100644 --- a/packages/generated/client-types/src/lib/models/AdminOrderEditItemChangeDeleteRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminOrderEditItemChangeDeleteRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of deleting order edit item changes. + */ export interface AdminOrderEditItemChangeDeleteRes { /** * The ID of the deleted Order Edit Item Change. diff --git a/packages/generated/client-types/src/lib/models/AdminOrderEditsListRes.ts b/packages/generated/client-types/src/lib/models/AdminOrderEditsListRes.ts index bd6a33a8b7..41715a99d8 100644 --- a/packages/generated/client-types/src/lib/models/AdminOrderEditsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminOrderEditsListRes.ts @@ -7,6 +7,9 @@ import type { LineItem } from "./LineItem" import type { OrderEdit } from "./OrderEdit" import type { OrderItemChange } from "./OrderItemChange" +/** + * The list of order edits with pagination fields. + */ export interface AdminOrderEditsListRes { /** * An array of order edit details diff --git a/packages/generated/client-types/src/lib/models/AdminOrderEditsRes.ts b/packages/generated/client-types/src/lib/models/AdminOrderEditsRes.ts index a9539b39b4..1d4e52a532 100644 --- a/packages/generated/client-types/src/lib/models/AdminOrderEditsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminOrderEditsRes.ts @@ -7,6 +7,9 @@ import type { LineItem } from "./LineItem" import type { OrderEdit } from "./OrderEdit" import type { OrderItemChange } from "./OrderItemChange" +/** + * The order edit details. + */ export interface AdminOrderEditsRes { /** * Order edit details diff --git a/packages/generated/client-types/src/lib/models/AdminOrdersListRes.ts b/packages/generated/client-types/src/lib/models/AdminOrdersListRes.ts index 943b309ffa..352d856591 100644 --- a/packages/generated/client-types/src/lib/models/AdminOrdersListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminOrdersListRes.ts @@ -18,6 +18,9 @@ import type { ReturnItem } from "./ReturnItem" import type { ShippingMethod } from "./ShippingMethod" import type { Swap } from "./Swap" +/** + * The list of orders with pagination fields. + */ export interface AdminOrdersListRes { /** * An array of order details. diff --git a/packages/generated/client-types/src/lib/models/AdminOrdersRes.ts b/packages/generated/client-types/src/lib/models/AdminOrdersRes.ts index 3ee3d9ed9b..26230b915b 100644 --- a/packages/generated/client-types/src/lib/models/AdminOrdersRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminOrdersRes.ts @@ -18,6 +18,9 @@ import type { ReturnItem } from "./ReturnItem" import type { ShippingMethod } from "./ShippingMethod" import type { Swap } from "./Swap" +/** + * The order's details. + */ export interface AdminOrdersRes { /** * Order details. diff --git a/packages/generated/client-types/src/lib/models/AdminPaymentCollectionDeleteRes.ts b/packages/generated/client-types/src/lib/models/AdminPaymentCollectionDeleteRes.ts index 4235f5c016..a2b3ee7c60 100644 --- a/packages/generated/client-types/src/lib/models/AdminPaymentCollectionDeleteRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPaymentCollectionDeleteRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of deleting a payment collection. + */ export interface AdminPaymentCollectionDeleteRes { /** * The ID of the deleted Payment Collection. diff --git a/packages/generated/client-types/src/lib/models/AdminPaymentProvidersList.ts b/packages/generated/client-types/src/lib/models/AdminPaymentProvidersList.ts index 9a3138c329..c51f5e58d6 100644 --- a/packages/generated/client-types/src/lib/models/AdminPaymentProvidersList.ts +++ b/packages/generated/client-types/src/lib/models/AdminPaymentProvidersList.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PaymentProvider } from "./PaymentProvider" +/** + * The list of payment providers in a store. + */ export interface AdminPaymentProvidersList { /** * An array of payment providers details. diff --git a/packages/generated/client-types/src/lib/models/AdminPaymentRes.ts b/packages/generated/client-types/src/lib/models/AdminPaymentRes.ts index 3e4c33a873..2cd69a5218 100644 --- a/packages/generated/client-types/src/lib/models/AdminPaymentRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPaymentRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Payment } from "./Payment" +/** + * The payment's details. + */ export interface AdminPaymentRes { /** * Payment details diff --git a/packages/generated/client-types/src/lib/models/AdminPostDiscountsDiscountConditionsConditionBatchReq.ts b/packages/generated/client-types/src/lib/models/AdminPostDiscountsDiscountConditionsConditionBatchReq.ts index 06f1ad97f6..777ef0eaa8 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostDiscountsDiscountConditionsConditionBatchReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostDiscountsDiscountConditionsConditionBatchReq.ts @@ -9,7 +9,7 @@ export interface AdminPostDiscountsDiscountConditionsConditionBatchReq { */ resources: Array<{ /** - * The id of the item + * The ID of the item */ id: string }> diff --git a/packages/generated/client-types/src/lib/models/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.ts b/packages/generated/client-types/src/lib/models/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.ts index ab9b0845f8..6f870836b7 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostDraftOrdersDraftOrderRegisterPaymentRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Order } from "./Order" +/** + * The order's details. + */ export interface AdminPostDraftOrdersDraftOrderRegisterPaymentRes { /** * Order's details. diff --git a/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsInventoryItemReq.ts b/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsInventoryItemReq.ts index db9248d414..ad246b3d2f 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsInventoryItemReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsInventoryItemReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The attributes to update in an inventory item. + */ export interface AdminPostInventoryItemsInventoryItemReq { /** * The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers. @@ -36,6 +39,18 @@ export interface AdminPostInventoryItemsInventoryItemReq { * The length of the Inventory Item. May be used in shipping rate calculations. */ length?: number + /** + * The inventory item's title. + */ + title?: string + /** + * The inventory item's description. + */ + description?: string + /** + * The inventory item's thumbnail. + */ + thumbnail?: string /** * Whether the item requires shipping. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsReq.ts index 1292108028..430d4b5d54 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostInventoryItemsReq.ts @@ -68,6 +68,18 @@ export interface AdminPostInventoryItemsReq { * The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers. */ material?: string + /** + * The inventory item's title. + */ + title?: string + /** + * The inventory item's description. + */ + description?: string + /** + * The inventory item's thumbnail. + */ + thumbnail?: string /** * An optional set of key-value pairs with additional information. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostInvitesInviteAcceptReq.ts b/packages/generated/client-types/src/lib/models/AdminPostInvitesInviteAcceptReq.ts index 6d62461d66..6f9954c21d 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostInvitesInviteAcceptReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostInvitesInviteAcceptReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of the invite to be accepted. + */ export interface AdminPostInvitesInviteAcceptReq { /** * The token of the invite to accept. This is a unique token generated when the invite was created or resent. diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.ts index f7bf353b37..edefcd0e4e 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsClaimFulfillmentsReq.ts @@ -12,4 +12,8 @@ export interface AdminPostOrdersOrderClaimsClaimFulfillmentsReq { * If set to `true`, no notification will be sent to the customer related to this Claim. */ no_notification?: boolean + /** + * The ID of the fulfillment's location. + */ + location_id?: string } diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsReq.ts index 35dd628ec3..3df11c8a99 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderClaimsReq.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { AddressPayload } from "./AddressPayload" +/** + * The details of the claim to be created. + */ export interface AdminPostOrdersOrderClaimsReq { /** * The type of the Claim. This will determine how the Claim is treated: `replace` Claims will result in a Fulfillment with new items being created, while a `refund` Claim will refund the amount paid for the claimed items. @@ -98,6 +101,10 @@ export interface AdminPostOrdersOrderClaimsReq { * If set to true no notification will be send related to this Claim. */ no_notification?: boolean + /** + * The ID of the location used for the associated return. + */ + return_location_id?: string /** * An optional set of key-value pairs to hold additional information. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderFulfillmentsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderFulfillmentsReq.ts index e06e86a10c..4f57f08123 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderFulfillmentsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderFulfillmentsReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of the fulfillment to be created. + */ export interface AdminPostOrdersOrderFulfillmentsReq { /** * The Line Items to include in the Fulfillment. @@ -17,6 +20,10 @@ export interface AdminPostOrdersOrderFulfillmentsReq { */ quantity: number }> + /** + * The ID of the location where the items will be fulfilled from. + */ + location_id?: string /** * If set to `true`, no notification will be sent to the customer related to this fulfillment. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReq.ts index 1fec3477a3..00897ab79c 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReq.ts @@ -9,7 +9,7 @@ import type { LineItem } from "./LineItem" export interface AdminPostOrdersOrderReq { /** - * the email associated with the order + * The email associated with the order */ email?: string /** diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReturnsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReturnsReq.ts index ba0313ae80..0b7e23001e 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReturnsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderReturnsReq.ts @@ -54,4 +54,8 @@ export interface AdminPostOrdersOrderReturnsReq { * The amount to refund. */ refund?: number + /** + * The ID of the location used for the return. + */ + location_id?: string } diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderShippingMethodsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderShippingMethodsReq.ts index 297f1f1ddd..be58d02efb 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderShippingMethodsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderShippingMethodsReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The shipping method's details. + */ export interface AdminPostOrdersOrderShippingMethodsReq { /** * The price (excluding VAT) that should be charged for the Shipping Method @@ -15,5 +18,5 @@ export interface AdminPostOrdersOrderShippingMethodsReq { /** * The data required for the Shipping Option to create a Shipping Method. This depends on the Fulfillment Provider. */ - date?: Record + data?: Record } diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsReq.ts index 599ab7489a..1a0be7c9b1 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsReq.ts @@ -51,6 +51,10 @@ export interface AdminPostOrdersOrderSwapsReq { */ quantity: number }> + /** + * The ID of the sales channel associated with the swap. + */ + sales_channel_id?: string /** * An array of custom shipping options to potentially create a Shipping Method from to send the additional items. */ @@ -68,6 +72,10 @@ export interface AdminPostOrdersOrderSwapsReq { * If set to `true`, no notification will be sent to the customer related to this Swap. */ no_notification?: boolean + /** + * The ID of the location used for the associated return. + */ + return_location_id?: string /** * If set to `true`, swaps can be completed with items out of stock */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.ts index 2a983f8de2..85db1d8917 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostOrdersOrderSwapsSwapFulfillmentsReq.ts @@ -12,4 +12,8 @@ export interface AdminPostOrdersOrderSwapsSwapFulfillmentsReq { * If set to `true`, no notification will be sent to the customer related to this swap. */ no_notification?: boolean + /** + * The ID of the fulfillment's location. + */ + location_id?: string } diff --git a/packages/generated/client-types/src/lib/models/AdminPostProductsProductReq.ts b/packages/generated/client-types/src/lib/models/AdminPostProductsProductReq.ts index 8411f1ea81..8ba2ec36e6 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostProductsProductReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostProductsProductReq.ts @@ -214,6 +214,10 @@ export interface AdminPostProductsProductReq { * The width of the Product. */ width?: number + /** + * The Harmonized System code of the product variant. + */ + hs_code?: string /** * The country of origin of the Product. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostReservationsReq.ts b/packages/generated/client-types/src/lib/models/AdminPostReservationsReq.ts index 0c7d8c7597..5806f2d331 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostReservationsReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostReservationsReq.ts @@ -20,6 +20,10 @@ export interface AdminPostReservationsReq { * The quantity to reserve. */ quantity: number + /** + * The reservation's description. + */ + description?: string /** * An optional set of key-value pairs with additional information. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostReservationsReservationReq.ts b/packages/generated/client-types/src/lib/models/AdminPostReservationsReservationReq.ts index 00686df56d..fb6bb939da 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostReservationsReservationReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostReservationsReservationReq.ts @@ -12,6 +12,10 @@ export interface AdminPostReservationsReservationReq { * The quantity to reserve. */ quantity?: number + /** + * The reservation's description. + */ + description?: string /** * An optional set of key-value pairs with additional information. */ diff --git a/packages/generated/client-types/src/lib/models/AdminPostReturnsReturnReceiveReq.ts b/packages/generated/client-types/src/lib/models/AdminPostReturnsReturnReceiveReq.ts index 78cdfb9b90..76c24ef1d7 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostReturnsReturnReceiveReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostReturnsReturnReceiveReq.ts @@ -21,4 +21,8 @@ export interface AdminPostReturnsReturnReceiveReq { * The amount to refund. */ refund?: number + /** + * The ID of the location to return items from. + */ + location_id?: string } diff --git a/packages/generated/client-types/src/lib/models/AdminPostShippingProfilesReq.ts b/packages/generated/client-types/src/lib/models/AdminPostShippingProfilesReq.ts index da33d3173b..3b03651786 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostShippingProfilesReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostShippingProfilesReq.ts @@ -12,4 +12,8 @@ export interface AdminPostShippingProfilesReq { * The type of the Shipping Profile */ type: "default" | "gift_card" | "custom" + /** + * An optional set of key-value pairs with additional information. + */ + metadata?: Record } diff --git a/packages/generated/client-types/src/lib/models/AdminPostStockLocationsLocationReq.ts b/packages/generated/client-types/src/lib/models/AdminPostStockLocationsLocationReq.ts index 93fc365b26..2547849afd 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostStockLocationsLocationReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostStockLocationsLocationReq.ts @@ -18,5 +18,8 @@ export interface AdminPostStockLocationsLocationReq { * An optional key-value map with additional details */ metadata?: Record + /** + * The data of an associated address to create or update. + */ address?: StockLocationAddressInput } diff --git a/packages/generated/client-types/src/lib/models/AdminPostStockLocationsReqAddress.ts b/packages/generated/client-types/src/lib/models/AdminPostStockLocationsReqAddress.ts index aa811a9a1d..a2c4d07fc5 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostStockLocationsReqAddress.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostStockLocationsReqAddress.ts @@ -21,7 +21,7 @@ export interface AdminPostStockLocationsReqAddress { */ city?: string /** - * The 2 character ISO code for the country. + * The two character ISO code for the country. */ country_code: string /** diff --git a/packages/generated/client-types/src/lib/models/AdminPostTaxRatesTaxRateProductTypesReq.ts b/packages/generated/client-types/src/lib/models/AdminPostTaxRatesTaxRateProductTypesReq.ts index 2f7a3b0654..c5ec87ad34 100644 --- a/packages/generated/client-types/src/lib/models/AdminPostTaxRatesTaxRateProductTypesReq.ts +++ b/packages/generated/client-types/src/lib/models/AdminPostTaxRatesTaxRateProductTypesReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The product types to add to the tax rate. + */ export interface AdminPostTaxRatesTaxRateProductTypesReq { /** * The IDs of the types of products to associate with this tax rate diff --git a/packages/generated/client-types/src/lib/models/AdminPriceListDeleteBatchRes.ts b/packages/generated/client-types/src/lib/models/AdminPriceListDeleteBatchRes.ts index 9db449fa2c..9a467dd476 100644 --- a/packages/generated/client-types/src/lib/models/AdminPriceListDeleteBatchRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPriceListDeleteBatchRes.ts @@ -3,7 +3,13 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of deleting a price list. + */ export interface AdminPriceListDeleteBatchRes { + /** + * The IDs of the deleted prices. + */ ids: Array /** * The type of the object that was deleted. A price is also named `money-amount`. diff --git a/packages/generated/client-types/src/lib/models/AdminPriceListRes.ts b/packages/generated/client-types/src/lib/models/AdminPriceListRes.ts index 09c926e5f6..cffb34a24b 100644 --- a/packages/generated/client-types/src/lib/models/AdminPriceListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPriceListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PriceList } from "./PriceList" +/** + * The price list's details. + */ export interface AdminPriceListRes { /** * Price List details. diff --git a/packages/generated/client-types/src/lib/models/AdminPriceListsListRes.ts b/packages/generated/client-types/src/lib/models/AdminPriceListsListRes.ts index b7302073c4..d58868f7d7 100644 --- a/packages/generated/client-types/src/lib/models/AdminPriceListsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPriceListsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PriceList } from "./PriceList" +/** + * The list of price lists with pagination fields. + */ export interface AdminPriceListsListRes { /** * An array of price lists details. diff --git a/packages/generated/client-types/src/lib/models/AdminPriceListsProductsListRes.ts b/packages/generated/client-types/src/lib/models/AdminPriceListsProductsListRes.ts index 091f67a9c2..a75086c8b4 100644 --- a/packages/generated/client-types/src/lib/models/AdminPriceListsProductsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPriceListsProductsListRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Product } from "./Product" import type { ProductVariant } from "./ProductVariant" +/** + * The list of products with pagination fields. + */ export interface AdminPriceListsProductsListRes { /** * An array of products details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductCategoriesCategoryRes.ts b/packages/generated/client-types/src/lib/models/AdminProductCategoriesCategoryRes.ts index 0a4de72a53..c287969b01 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductCategoriesCategoryRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductCategoriesCategoryRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCategory } from "./ProductCategory" +/** + * The product category's details. + */ export interface AdminProductCategoriesCategoryRes { /** * Product category details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductCategoriesListRes.ts b/packages/generated/client-types/src/lib/models/AdminProductCategoriesListRes.ts index f3c23dbc90..e5aa15f8fc 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductCategoriesListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductCategoriesListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCategory } from "./ProductCategory" +/** + * The list of product categories with pagination fields. + */ export interface AdminProductCategoriesListRes { /** * An array of product category details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductTagsListRes.ts b/packages/generated/client-types/src/lib/models/AdminProductTagsListRes.ts index 44f13e066d..720fe3d3da 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductTagsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductTagsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductTag } from "./ProductTag" +/** + * The list of product tags with pagination fields. + */ export interface AdminProductTagsListRes { /** * An array of product tag details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductTypesListRes.ts b/packages/generated/client-types/src/lib/models/AdminProductTypesListRes.ts index a93ac137a4..73efb0cec1 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductTypesListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductTypesListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductType } from "./ProductType" +/** + * The list of product types with pagination fields. + */ export interface AdminProductTypesListRes { /** * An array of product types details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductsDeleteOptionRes.ts b/packages/generated/client-types/src/lib/models/AdminProductsDeleteOptionRes.ts index cef61c03a2..3130418b79 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductsDeleteOptionRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductsDeleteOptionRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedProduct } from "./PricedProduct" import type { ProductVariant } from "./ProductVariant" +/** + * The details of deleting a product's option. + */ export interface AdminProductsDeleteOptionRes { /** * The ID of the deleted Product Option diff --git a/packages/generated/client-types/src/lib/models/AdminProductsDeleteRes.ts b/packages/generated/client-types/src/lib/models/AdminProductsDeleteRes.ts index 31943a690f..18a55fa861 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductsDeleteRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductsDeleteRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of deleting a product. + */ export interface AdminProductsDeleteRes { /** * The ID of the deleted Product. diff --git a/packages/generated/client-types/src/lib/models/AdminProductsDeleteVariantRes.ts b/packages/generated/client-types/src/lib/models/AdminProductsDeleteVariantRes.ts index 2cc095fb1c..1b56db7d15 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductsDeleteVariantRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductsDeleteVariantRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedProduct } from "./PricedProduct" import type { ProductVariant } from "./ProductVariant" +/** + * The details of deleting a product's variant. + */ export interface AdminProductsDeleteVariantRes { /** * The ID of the deleted Product Variant. diff --git a/packages/generated/client-types/src/lib/models/AdminProductsListRes.ts b/packages/generated/client-types/src/lib/models/AdminProductsListRes.ts index 4757967b88..e0970dd551 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductsListRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedProduct } from "./PricedProduct" import type { ProductVariant } from "./ProductVariant" +/** + * The list of products with pagination fields. + */ export interface AdminProductsListRes { /** * An array of products details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductsListTagsRes.ts b/packages/generated/client-types/src/lib/models/AdminProductsListTagsRes.ts index c009eebc8e..909901f4df 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductsListTagsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductsListTagsRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The usage details of product tags. + */ export interface AdminProductsListTagsRes { /** * An array of product tags details. diff --git a/packages/generated/client-types/src/lib/models/AdminProductsRes.ts b/packages/generated/client-types/src/lib/models/AdminProductsRes.ts index 272d837ff3..1dc05f1181 100644 --- a/packages/generated/client-types/src/lib/models/AdminProductsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminProductsRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedProduct } from "./PricedProduct" import type { ProductVariant } from "./ProductVariant" +/** + * The product's details. + */ export interface AdminProductsRes { /** * Product details. diff --git a/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListRes.ts b/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListRes.ts index ff1a800a37..535bd69f89 100644 --- a/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PublishableApiKey } from "./PublishableApiKey" +/** + * The list of publishable API keys with pagination fields. + */ export interface AdminPublishableApiKeysListRes { /** * An array of publishable API keys details. diff --git a/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListSalesChannelsRes.ts b/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListSalesChannelsRes.ts index e279e53042..66c1a49d72 100644 --- a/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListSalesChannelsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysListSalesChannelsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { SalesChannel } from "./SalesChannel" +/** + * The list of sales channel. + */ export interface AdminPublishableApiKeysListSalesChannelsRes { /** * An array of sales channels details. diff --git a/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysRes.ts b/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysRes.ts index 42170e7911..43e6c66cd2 100644 --- a/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminPublishableApiKeysRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PublishableApiKey } from "./PublishableApiKey" +/** + * The publishable API key's details. + */ export interface AdminPublishableApiKeysRes { /** * Publishable API key details. diff --git a/packages/generated/client-types/src/lib/models/AdminRefundRes.ts b/packages/generated/client-types/src/lib/models/AdminRefundRes.ts index 4028ea04b8..7f42ba0759 100644 --- a/packages/generated/client-types/src/lib/models/AdminRefundRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminRefundRes.ts @@ -5,9 +5,12 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Refund } from "./Refund" +/** + * The refund's details. + */ export interface AdminRefundRes { /** - * Refund details + * Refund details. */ refund: Refund } diff --git a/packages/generated/client-types/src/lib/models/AdminRegionsListRes.ts b/packages/generated/client-types/src/lib/models/AdminRegionsListRes.ts index bac8373004..a79f78eaa2 100644 --- a/packages/generated/client-types/src/lib/models/AdminRegionsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminRegionsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Region } from "./Region" +/** + * The list of regions with pagination fields. + */ export interface AdminRegionsListRes { /** * An array of regions details. diff --git a/packages/generated/client-types/src/lib/models/AdminRegionsRes.ts b/packages/generated/client-types/src/lib/models/AdminRegionsRes.ts index 7c40be80cf..368f8af860 100644 --- a/packages/generated/client-types/src/lib/models/AdminRegionsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminRegionsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Region } from "./Region" +/** + * The region's details. + */ export interface AdminRegionsRes { /** * Region details. diff --git a/packages/generated/client-types/src/lib/models/AdminReservationsListRes.ts b/packages/generated/client-types/src/lib/models/AdminReservationsListRes.ts index d386c42bab..0f2cc4fd7b 100644 --- a/packages/generated/client-types/src/lib/models/AdminReservationsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReservationsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ExtendedReservationItem } from "./ExtendedReservationItem" +/** + * The list of reservations with pagination fields. + */ export interface AdminReservationsListRes { /** * An array of reservations details. diff --git a/packages/generated/client-types/src/lib/models/AdminReservationsRes.ts b/packages/generated/client-types/src/lib/models/AdminReservationsRes.ts index 641d721663..7286bc603d 100644 --- a/packages/generated/client-types/src/lib/models/AdminReservationsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReservationsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ReservationItemDTO } from "./ReservationItemDTO" +/** + * The reservation's details. + */ export interface AdminReservationsRes { /** * Reservation details. diff --git a/packages/generated/client-types/src/lib/models/AdminReturnReasonsListRes.ts b/packages/generated/client-types/src/lib/models/AdminReturnReasonsListRes.ts index fb985e22a5..1636eaacbf 100644 --- a/packages/generated/client-types/src/lib/models/AdminReturnReasonsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReturnReasonsListRes.ts @@ -5,7 +5,13 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ReturnReason } from "./ReturnReason" +/** + * The list of return reasons. + */ export interface AdminReturnReasonsListRes { + /** + * The list of return reasons. + */ return_reasons: Array< SetRelation > diff --git a/packages/generated/client-types/src/lib/models/AdminReturnReasonsRes.ts b/packages/generated/client-types/src/lib/models/AdminReturnReasonsRes.ts index c48622d74c..d62aef3693 100644 --- a/packages/generated/client-types/src/lib/models/AdminReturnReasonsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReturnReasonsRes.ts @@ -5,7 +5,13 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ReturnReason } from "./ReturnReason" +/** + * The return reason's details. + */ export interface AdminReturnReasonsRes { + /** + * The return reason's details. + */ return_reason: SetRelation< ReturnReason, "parent_return_reason" | "return_reason_children" diff --git a/packages/generated/client-types/src/lib/models/AdminReturnsCancelRes.ts b/packages/generated/client-types/src/lib/models/AdminReturnsCancelRes.ts index be3adcbd9b..f527202b98 100644 --- a/packages/generated/client-types/src/lib/models/AdminReturnsCancelRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReturnsCancelRes.ts @@ -14,6 +14,9 @@ import type { ReturnItem } from "./ReturnItem" import type { ShippingMethod } from "./ShippingMethod" import type { Swap } from "./Swap" +/** + * The associated order's details. + */ export interface AdminReturnsCancelRes { /** * Order details. diff --git a/packages/generated/client-types/src/lib/models/AdminReturnsListRes.ts b/packages/generated/client-types/src/lib/models/AdminReturnsListRes.ts index ef46aed547..d82b74a885 100644 --- a/packages/generated/client-types/src/lib/models/AdminReturnsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReturnsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Return } from "./Return" +/** + * The list of returns with pagination fields. + */ export interface AdminReturnsListRes { /** * An array of returns details. diff --git a/packages/generated/client-types/src/lib/models/AdminReturnsRes.ts b/packages/generated/client-types/src/lib/models/AdminReturnsRes.ts index bba79e52ca..c6f4749de3 100644 --- a/packages/generated/client-types/src/lib/models/AdminReturnsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminReturnsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Return } from "./Return" +/** + * The return's details. + */ export interface AdminReturnsRes { /** * Return details. diff --git a/packages/generated/client-types/src/lib/models/AdminSalesChannelsListRes.ts b/packages/generated/client-types/src/lib/models/AdminSalesChannelsListRes.ts index 79a35f744f..b4358494b8 100644 --- a/packages/generated/client-types/src/lib/models/AdminSalesChannelsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminSalesChannelsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { SalesChannel } from "./SalesChannel" +/** + * The list of sales channels with pagination fields. + */ export interface AdminSalesChannelsListRes { /** * An array of sales channels details. diff --git a/packages/generated/client-types/src/lib/models/AdminSalesChannelsRes.ts b/packages/generated/client-types/src/lib/models/AdminSalesChannelsRes.ts index d823bfb037..a53880caad 100644 --- a/packages/generated/client-types/src/lib/models/AdminSalesChannelsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminSalesChannelsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { SalesChannel } from "./SalesChannel" +/** + * The sales channel's details. + */ export interface AdminSalesChannelsRes { /** * Sales Channel's details. diff --git a/packages/generated/client-types/src/lib/models/AdminShippingOptionsListRes.ts b/packages/generated/client-types/src/lib/models/AdminShippingOptionsListRes.ts index 221b08f07f..d79829c537 100644 --- a/packages/generated/client-types/src/lib/models/AdminShippingOptionsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminShippingOptionsListRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Region } from "./Region" import type { ShippingOption } from "./ShippingOption" +/** + * The list of shipping options with pagination fields. + */ export interface AdminShippingOptionsListRes { /** * An array of shipping options details. diff --git a/packages/generated/client-types/src/lib/models/AdminShippingOptionsRes.ts b/packages/generated/client-types/src/lib/models/AdminShippingOptionsRes.ts index 410d619dda..81c6b25580 100644 --- a/packages/generated/client-types/src/lib/models/AdminShippingOptionsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminShippingOptionsRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Region } from "./Region" import type { ShippingOption } from "./ShippingOption" +/** + * The shipping option's details. + */ export interface AdminShippingOptionsRes { /** * Shipping option details. diff --git a/packages/generated/client-types/src/lib/models/AdminShippingProfilesListRes.ts b/packages/generated/client-types/src/lib/models/AdminShippingProfilesListRes.ts index 51f85653ba..095807c537 100644 --- a/packages/generated/client-types/src/lib/models/AdminShippingProfilesListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminShippingProfilesListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ShippingProfile } from "./ShippingProfile" +/** + * The list of shipping profiles. + */ export interface AdminShippingProfilesListRes { /** * An array of shipping profiles details. diff --git a/packages/generated/client-types/src/lib/models/AdminShippingProfilesRes.ts b/packages/generated/client-types/src/lib/models/AdminShippingProfilesRes.ts index f3e44ad469..876270d250 100644 --- a/packages/generated/client-types/src/lib/models/AdminShippingProfilesRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminShippingProfilesRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ShippingProfile } from "./ShippingProfile" +/** + * The shipping profile's details. + */ export interface AdminShippingProfilesRes { /** * Shipping profile details. diff --git a/packages/generated/client-types/src/lib/models/AdminStockLocationsListRes.ts b/packages/generated/client-types/src/lib/models/AdminStockLocationsListRes.ts index c39ffdb49e..461de6f7ae 100644 --- a/packages/generated/client-types/src/lib/models/AdminStockLocationsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminStockLocationsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { StockLocationExpandedDTO } from "./StockLocationExpandedDTO" +/** + * The list of stock locations with pagination fields. + */ export interface AdminStockLocationsListRes { stock_locations: Array /** diff --git a/packages/generated/client-types/src/lib/models/AdminStockLocationsRes.ts b/packages/generated/client-types/src/lib/models/AdminStockLocationsRes.ts index 3d5e311375..a686f0c606 100644 --- a/packages/generated/client-types/src/lib/models/AdminStockLocationsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminStockLocationsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { StockLocationExpandedDTO } from "./StockLocationExpandedDTO" +/** + * The stock location's details. + */ export interface AdminStockLocationsRes { /** * Stock location details. diff --git a/packages/generated/client-types/src/lib/models/AdminStoresRes.ts b/packages/generated/client-types/src/lib/models/AdminStoresRes.ts index 8c95953131..7d74991b49 100644 --- a/packages/generated/client-types/src/lib/models/AdminStoresRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminStoresRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Store } from "./Store" +/** + * The store's details. + */ export interface AdminStoresRes { /** * Store details. diff --git a/packages/generated/client-types/src/lib/models/AdminSwapsListRes.ts b/packages/generated/client-types/src/lib/models/AdminSwapsListRes.ts index 4baaf5005c..e044e44b46 100644 --- a/packages/generated/client-types/src/lib/models/AdminSwapsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminSwapsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Swap } from "./Swap" +/** + * The list of swaps with pagination fields. + */ export interface AdminSwapsListRes { /** * An array of swaps details. diff --git a/packages/generated/client-types/src/lib/models/AdminSwapsRes.ts b/packages/generated/client-types/src/lib/models/AdminSwapsRes.ts index 1bc5212477..6ef9e2f3b4 100644 --- a/packages/generated/client-types/src/lib/models/AdminSwapsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminSwapsRes.ts @@ -9,6 +9,9 @@ import type { LineItem } from "./LineItem" import type { ShippingMethod } from "./ShippingMethod" import type { Swap } from "./Swap" +/** + * The swap's details. + */ export interface AdminSwapsRes { /** * Swap details. diff --git a/packages/generated/client-types/src/lib/models/AdminTaxProvidersList.ts b/packages/generated/client-types/src/lib/models/AdminTaxProvidersList.ts index 357b2db8b5..68abd50f42 100644 --- a/packages/generated/client-types/src/lib/models/AdminTaxProvidersList.ts +++ b/packages/generated/client-types/src/lib/models/AdminTaxProvidersList.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { TaxProvider } from "./TaxProvider" +/** + * The list of tax providers in a store. + */ export interface AdminTaxProvidersList { /** * An array of tax providers details. diff --git a/packages/generated/client-types/src/lib/models/AdminTaxRatesListRes.ts b/packages/generated/client-types/src/lib/models/AdminTaxRatesListRes.ts index 520eb90159..4cb55f8b91 100644 --- a/packages/generated/client-types/src/lib/models/AdminTaxRatesListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminTaxRatesListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { TaxRate } from "./TaxRate" +/** + * The list of tax rates with pagination fields. + */ export interface AdminTaxRatesListRes { /** * An array of tax rate details. diff --git a/packages/generated/client-types/src/lib/models/AdminTaxRatesRes.ts b/packages/generated/client-types/src/lib/models/AdminTaxRatesRes.ts index 069bb0e29a..6b70fbb018 100644 --- a/packages/generated/client-types/src/lib/models/AdminTaxRatesRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminTaxRatesRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { TaxRate } from "./TaxRate" +/** + * The tax rate's details. + */ export interface AdminTaxRatesRes { /** * Tax rate details. diff --git a/packages/generated/client-types/src/lib/models/AdminUploadsDownloadUrlRes.ts b/packages/generated/client-types/src/lib/models/AdminUploadsDownloadUrlRes.ts index c4d31f6233..30c97bd485 100644 --- a/packages/generated/client-types/src/lib/models/AdminUploadsDownloadUrlRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminUploadsDownloadUrlRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The download URL details. + */ export interface AdminUploadsDownloadUrlRes { /** * The Download URL of the file diff --git a/packages/generated/client-types/src/lib/models/AdminUploadsRes.ts b/packages/generated/client-types/src/lib/models/AdminUploadsRes.ts index f41b4d85b6..f33d20df5c 100644 --- a/packages/generated/client-types/src/lib/models/AdminUploadsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminUploadsRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The list of uploaded files. + */ export interface AdminUploadsRes { /** * Uploaded files details. diff --git a/packages/generated/client-types/src/lib/models/AdminUserRes.ts b/packages/generated/client-types/src/lib/models/AdminUserRes.ts index f9427aa223..ea39d65e69 100644 --- a/packages/generated/client-types/src/lib/models/AdminUserRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminUserRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { User } from "./User" +/** + * The user's details. + */ export interface AdminUserRes { /** * User details. diff --git a/packages/generated/client-types/src/lib/models/AdminUsersListRes.ts b/packages/generated/client-types/src/lib/models/AdminUsersListRes.ts index 07376ce6dc..4b182bd4b8 100644 --- a/packages/generated/client-types/src/lib/models/AdminUsersListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminUsersListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { User } from "./User" +/** + * The list of users. + */ export interface AdminUsersListRes { /** * An array of users details. diff --git a/packages/generated/client-types/src/lib/models/AdminVariantsListRes.ts b/packages/generated/client-types/src/lib/models/AdminVariantsListRes.ts index 957f9f5827..34c72e2ee0 100644 --- a/packages/generated/client-types/src/lib/models/AdminVariantsListRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminVariantsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedVariant } from "./PricedVariant" +/** + * The list of variants with pagination fields. + */ export interface AdminVariantsListRes { /** * An array of product variant details. diff --git a/packages/generated/client-types/src/lib/models/AdminVariantsRes.ts b/packages/generated/client-types/src/lib/models/AdminVariantsRes.ts index b75cd79441..2b886a4e25 100644 --- a/packages/generated/client-types/src/lib/models/AdminVariantsRes.ts +++ b/packages/generated/client-types/src/lib/models/AdminVariantsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedVariant } from "./PricedVariant" +/** + * The product variant's details. + */ export interface AdminVariantsRes { /** * Product variant's details. diff --git a/packages/generated/client-types/src/lib/models/ExtendedStoreDTO.ts b/packages/generated/client-types/src/lib/models/ExtendedStoreDTO.ts index 8c0318e3d5..2348dbbdaf 100644 --- a/packages/generated/client-types/src/lib/models/ExtendedStoreDTO.ts +++ b/packages/generated/client-types/src/lib/models/ExtendedStoreDTO.ts @@ -10,8 +10,20 @@ import type { PaymentProvider } from "./PaymentProvider" import type { Store } from "./Store" export type ExtendedStoreDTO = Store & { + /** + * The store's payment providers. + */ payment_providers: PaymentProvider + /** + * The store's fulfillment providers. + */ fulfillment_providers: FulfillmentProvider + /** + * The feature flags enabled in the store's backend. + */ feature_flags: FeatureFlagsResponse + /** + * The modules installed in the store's backend. + */ modules: ModulesResponse } diff --git a/packages/generated/client-types/src/lib/models/InventoryItemDTO.ts b/packages/generated/client-types/src/lib/models/InventoryItemDTO.ts index 7978a3ecb5..96fa9a41f7 100644 --- a/packages/generated/client-types/src/lib/models/InventoryItemDTO.ts +++ b/packages/generated/client-types/src/lib/models/InventoryItemDTO.ts @@ -4,6 +4,10 @@ import { SetRelation, Merge } from "../core/ModelUtils" export interface InventoryItemDTO { + /** + * The inventory item's ID. + */ + id?: string /** * The Stock Keeping Unit (SKU) code of the Inventory Item. */ diff --git a/packages/generated/client-types/src/lib/models/PaymentCollection.ts b/packages/generated/client-types/src/lib/models/PaymentCollection.ts index 7e0d5546a1..8cb1536759 100644 --- a/packages/generated/client-types/src/lib/models/PaymentCollection.ts +++ b/packages/generated/client-types/src/lib/models/PaymentCollection.ts @@ -50,7 +50,7 @@ export interface PaymentCollection { */ region?: Region | null /** - * The 3 character ISO code for the currency this payment collection is associated with. + * The three character ISO code for the currency this payment collection is associated with. */ currency_code: string /** diff --git a/packages/generated/client-types/src/lib/models/PricedProduct.ts b/packages/generated/client-types/src/lib/models/PricedProduct.ts index ae31b3bc55..4acde7c407 100644 --- a/packages/generated/client-types/src/lib/models/PricedProduct.ts +++ b/packages/generated/client-types/src/lib/models/PricedProduct.ts @@ -7,5 +7,8 @@ import type { PricedVariant } from "./PricedVariant" import type { Product } from "./Product" export type PricedProduct = Product & { + /** + * The product variants and their prices. + */ variants?: Array } diff --git a/packages/generated/client-types/src/lib/models/ProductCategory.ts b/packages/generated/client-types/src/lib/models/ProductCategory.ts index 58a9e8fa3e..d25d665a90 100644 --- a/packages/generated/client-types/src/lib/models/ProductCategory.ts +++ b/packages/generated/client-types/src/lib/models/ProductCategory.ts @@ -17,6 +17,10 @@ export interface ProductCategory { * The product category's name */ name: string + /** + * The product category's description. + */ + description?: string /** * A unique string that identifies the Product Category - can for example be used in slug structures. */ diff --git a/packages/generated/client-types/src/lib/models/Region.ts b/packages/generated/client-types/src/lib/models/Region.ts index 554c5529f7..1b6aa0d0cb 100644 --- a/packages/generated/client-types/src/lib/models/Region.ts +++ b/packages/generated/client-types/src/lib/models/Region.ts @@ -23,7 +23,7 @@ export interface Region { */ name: string /** - * The 3 character currency code used in the region. + * The three character currency code used in the region. */ currency_code: string /** diff --git a/packages/generated/client-types/src/lib/models/StockLocationExpandedDTO.ts b/packages/generated/client-types/src/lib/models/StockLocationExpandedDTO.ts index 33760133e2..39a6ed0acc 100644 --- a/packages/generated/client-types/src/lib/models/StockLocationExpandedDTO.ts +++ b/packages/generated/client-types/src/lib/models/StockLocationExpandedDTO.ts @@ -7,5 +7,8 @@ import type { SalesChannel } from "./SalesChannel" import type { StockLocationDTO } from "./StockLocationDTO" export type StockLocationExpandedDTO = StockLocationDTO & { + /** + * The associated sales channels. + */ sales_channels?: SalesChannel } diff --git a/packages/generated/client-types/src/lib/models/Store.ts b/packages/generated/client-types/src/lib/models/Store.ts index 950f3610d9..dc5522fb54 100644 --- a/packages/generated/client-types/src/lib/models/Store.ts +++ b/packages/generated/client-types/src/lib/models/Store.ts @@ -19,7 +19,7 @@ export interface Store { */ name: string /** - * The 3 character currency code that is the default of the store. + * The three character currency code that is the default of the store. */ default_currency_code: string /** diff --git a/packages/generated/client-types/src/lib/models/StoreAuthRes.ts b/packages/generated/client-types/src/lib/models/StoreAuthRes.ts index d659300431..07f6ec593e 100644 --- a/packages/generated/client-types/src/lib/models/StoreAuthRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreAuthRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Customer } from "./Customer" import type { Order } from "./Order" +/** + * The customer's details. + */ export interface StoreAuthRes { /** * Customer's details. diff --git a/packages/generated/client-types/src/lib/models/StoreBearerAuthRes.ts b/packages/generated/client-types/src/lib/models/StoreBearerAuthRes.ts index e74a9e9f6b..293ecdb598 100644 --- a/packages/generated/client-types/src/lib/models/StoreBearerAuthRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreBearerAuthRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The access token details. + */ export interface StoreBearerAuthRes { /** * Access token that can be used to send authenticated requests. diff --git a/packages/generated/client-types/src/lib/models/StoreCartsRes.ts b/packages/generated/client-types/src/lib/models/StoreCartsRes.ts index bceb536bb1..2fbfde3b57 100644 --- a/packages/generated/client-types/src/lib/models/StoreCartsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCartsRes.ts @@ -11,6 +11,9 @@ import type { ProductVariant } from "./ProductVariant" import type { Region } from "./Region" import type { ShippingMethod } from "./ShippingMethod" +/** + * The cart's details. + */ export interface StoreCartsRes { /** * Cart details. diff --git a/packages/generated/client-types/src/lib/models/StoreCollectionsListRes.ts b/packages/generated/client-types/src/lib/models/StoreCollectionsListRes.ts index 680f753e72..acc2e6dd27 100644 --- a/packages/generated/client-types/src/lib/models/StoreCollectionsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCollectionsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCollection } from "./ProductCollection" +/** + * The list of product collections with pagination fields. + */ export interface StoreCollectionsListRes { /** * An array of product collections details diff --git a/packages/generated/client-types/src/lib/models/StoreCollectionsRes.ts b/packages/generated/client-types/src/lib/models/StoreCollectionsRes.ts index 6c9f82fe24..7a46c8bd7f 100644 --- a/packages/generated/client-types/src/lib/models/StoreCollectionsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCollectionsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCollection } from "./ProductCollection" +/** + * The details of the product collection. + */ export interface StoreCollectionsRes { /** * Product collection details. diff --git a/packages/generated/client-types/src/lib/models/StoreCompleteCartRes.ts b/packages/generated/client-types/src/lib/models/StoreCompleteCartRes.ts index 0ace830e5e..150344e0bf 100644 --- a/packages/generated/client-types/src/lib/models/StoreCompleteCartRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCompleteCartRes.ts @@ -7,6 +7,9 @@ import type { Cart } from "./Cart" import type { Order } from "./Order" import type { Swap } from "./Swap" +/** + * If the cart is completed successfully, this will have the created order or the swap's details, based on the cart's type. Otherwise, it'll be the cart's details. + */ export interface StoreCompleteCartRes { /** * The type of the data property. If the cart completion fails, type will be `cart` and the data object will be the cart's details. If the cart completion is successful and the cart is used for checkout, type will be `order` and the data object will be the order's details. If the cart completion is successful and the cart is used for swap creation, type will be `swap` and the data object will be the swap's details. diff --git a/packages/generated/client-types/src/lib/models/StoreCustomersListOrdersRes.ts b/packages/generated/client-types/src/lib/models/StoreCustomersListOrdersRes.ts index e8982052ad..ded411df06 100644 --- a/packages/generated/client-types/src/lib/models/StoreCustomersListOrdersRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCustomersListOrdersRes.ts @@ -15,6 +15,9 @@ import type { Region } from "./Region" import type { ShippingMethod } from "./ShippingMethod" import type { Swap } from "./Swap" +/** + * The list of the customer's orders with pagination fields. + */ export interface StoreCustomersListOrdersRes { /** * An array of orders details. diff --git a/packages/generated/client-types/src/lib/models/StoreCustomersListPaymentMethodsRes.ts b/packages/generated/client-types/src/lib/models/StoreCustomersListPaymentMethodsRes.ts index 6a88fcb57b..fd93d87caa 100644 --- a/packages/generated/client-types/src/lib/models/StoreCustomersListPaymentMethodsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCustomersListPaymentMethodsRes.ts @@ -3,9 +3,12 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The payment method's details. + */ export interface StoreCustomersListPaymentMethodsRes { /** - * An array of saved payment method details. + * The details of the saved payment methods. */ payment_methods: Array<{ /** diff --git a/packages/generated/client-types/src/lib/models/StoreCustomersRes.ts b/packages/generated/client-types/src/lib/models/StoreCustomersRes.ts index 95145f40d2..dc79cdf47c 100644 --- a/packages/generated/client-types/src/lib/models/StoreCustomersRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreCustomersRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Customer } from "./Customer" +/** + * The customer's details. + */ export interface StoreCustomersRes { /** * Customer details. diff --git a/packages/generated/client-types/src/lib/models/StoreGetAuthEmailRes.ts b/packages/generated/client-types/src/lib/models/StoreGetAuthEmailRes.ts index 262c4446c8..0a49cb568c 100644 --- a/packages/generated/client-types/src/lib/models/StoreGetAuthEmailRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreGetAuthEmailRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * Details on whether the email exists. + */ export interface StoreGetAuthEmailRes { /** * Whether email exists or not. diff --git a/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesCategoryRes.ts b/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesCategoryRes.ts index 3faa1fc3a6..90f6738680 100644 --- a/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesCategoryRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesCategoryRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCategory } from "./ProductCategory" +/** + * The product category's details. + */ export interface StoreGetProductCategoriesCategoryRes { /** * Product category details. diff --git a/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesRes.ts b/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesRes.ts index ffefed64e3..d34117a749 100644 --- a/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreGetProductCategoriesRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductCategory } from "./ProductCategory" +/** + * The list of product categories with pagination fields. + */ export interface StoreGetProductCategoriesRes { /** * An array of product categories details. diff --git a/packages/generated/client-types/src/lib/models/StoreGiftCardsRes.ts b/packages/generated/client-types/src/lib/models/StoreGiftCardsRes.ts index c6d239306f..74cd25d646 100644 --- a/packages/generated/client-types/src/lib/models/StoreGiftCardsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreGiftCardsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { GiftCard } from "./GiftCard" +/** + * The gift card's details. + */ export interface StoreGiftCardsRes { /** * Gift card details. diff --git a/packages/generated/client-types/src/lib/models/StoreOrderEditsRes.ts b/packages/generated/client-types/src/lib/models/StoreOrderEditsRes.ts index eacd54a219..a9d1b10f43 100644 --- a/packages/generated/client-types/src/lib/models/StoreOrderEditsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreOrderEditsRes.ts @@ -7,6 +7,9 @@ import type { LineItem } from "./LineItem" import type { OrderEdit } from "./OrderEdit" import type { OrderItemChange } from "./OrderItemChange" +/** + * The order edit's details. + */ export interface StoreOrderEditsRes { /** * Order edit details. diff --git a/packages/generated/client-types/src/lib/models/StoreOrdersRes.ts b/packages/generated/client-types/src/lib/models/StoreOrdersRes.ts index 7fd84e27b2..ad419f1a6c 100644 --- a/packages/generated/client-types/src/lib/models/StoreOrdersRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreOrdersRes.ts @@ -15,6 +15,9 @@ import type { Region } from "./Region" import type { ShippingMethod } from "./ShippingMethod" import type { Swap } from "./Swap" +/** + * The order's details. + */ export interface StoreOrdersRes { /** * Order details. diff --git a/packages/generated/client-types/src/lib/models/StorePaymentCollectionsRes.ts b/packages/generated/client-types/src/lib/models/StorePaymentCollectionsRes.ts index b03f83c15e..a17e4a5a4c 100644 --- a/packages/generated/client-types/src/lib/models/StorePaymentCollectionsRes.ts +++ b/packages/generated/client-types/src/lib/models/StorePaymentCollectionsRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PaymentCollection } from "./PaymentCollection" import type { Region } from "./Region" +/** + * The payment collection's details. + */ export interface StorePaymentCollectionsRes { /** * Payment collection's details. diff --git a/packages/generated/client-types/src/lib/models/StorePostCartReq.ts b/packages/generated/client-types/src/lib/models/StorePostCartReq.ts index f5afb0712d..fa74aa03f8 100644 --- a/packages/generated/client-types/src/lib/models/StorePostCartReq.ts +++ b/packages/generated/client-types/src/lib/models/StorePostCartReq.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The details of the cart to be created. + */ export interface StorePostCartReq { /** * The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency. If this parameter is not provided, the first region in the store is used by default. @@ -13,7 +16,7 @@ export interface StorePostCartReq { */ sales_channel_id?: string /** - * The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address. + * The two character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address. */ country_code?: string /** diff --git a/packages/generated/client-types/src/lib/models/StorePostPaymentCollectionsBatchSessionsReq.ts b/packages/generated/client-types/src/lib/models/StorePostPaymentCollectionsBatchSessionsReq.ts index faed4dabf8..8604178615 100644 --- a/packages/generated/client-types/src/lib/models/StorePostPaymentCollectionsBatchSessionsReq.ts +++ b/packages/generated/client-types/src/lib/models/StorePostPaymentCollectionsBatchSessionsReq.ts @@ -5,7 +5,7 @@ import { SetRelation, Merge } from "../core/ModelUtils" export interface StorePostPaymentCollectionsBatchSessionsReq { /** - * An array of payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted. + * Payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted. */ sessions: Array<{ /** diff --git a/packages/generated/client-types/src/lib/models/StorePostSearchRes.ts b/packages/generated/client-types/src/lib/models/StorePostSearchRes.ts index 027b70e5b6..d0f0c60b18 100644 --- a/packages/generated/client-types/src/lib/models/StorePostSearchRes.ts +++ b/packages/generated/client-types/src/lib/models/StorePostSearchRes.ts @@ -3,6 +3,9 @@ /* eslint-disable */ import { SetRelation, Merge } from "../core/ModelUtils" +/** + * The list of search results. + */ export type StorePostSearchRes = { /** * Array of search results. The format of the items depends on the search engine installed on the Medusa backend. diff --git a/packages/generated/client-types/src/lib/models/StoreProductTagsListRes.ts b/packages/generated/client-types/src/lib/models/StoreProductTagsListRes.ts index 201f32e83d..83dc07cdeb 100644 --- a/packages/generated/client-types/src/lib/models/StoreProductTagsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreProductTagsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ProductTag } from "./ProductTag" +/** + * The list of product tags with pagination fields. + */ export interface StoreProductTagsListRes { /** * An array of product tags details. diff --git a/packages/generated/client-types/src/lib/models/StoreProductsListRes.ts b/packages/generated/client-types/src/lib/models/StoreProductsListRes.ts index 1f523764f6..5bcc694bea 100644 --- a/packages/generated/client-types/src/lib/models/StoreProductsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreProductsListRes.ts @@ -7,6 +7,9 @@ import type { PricedProduct } from "./PricedProduct" import type { ProductOption } from "./ProductOption" import type { ProductVariant } from "./ProductVariant" +/** + * The list of products with pagination fields. + */ export interface StoreProductsListRes { /** * An array of products details. diff --git a/packages/generated/client-types/src/lib/models/StoreRegionsListRes.ts b/packages/generated/client-types/src/lib/models/StoreRegionsListRes.ts index 6831c5d868..245a42f772 100644 --- a/packages/generated/client-types/src/lib/models/StoreRegionsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreRegionsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Region } from "./Region" +/** + * The list of regions with pagination fields. + */ export interface StoreRegionsListRes { /** * An array of regions details. diff --git a/packages/generated/client-types/src/lib/models/StoreRegionsRes.ts b/packages/generated/client-types/src/lib/models/StoreRegionsRes.ts index 4024de7fc6..54ff688b3c 100644 --- a/packages/generated/client-types/src/lib/models/StoreRegionsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreRegionsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Region } from "./Region" +/** + * The region's details. + */ export interface StoreRegionsRes { /** * Region details. diff --git a/packages/generated/client-types/src/lib/models/StoreReturnReasonsListRes.ts b/packages/generated/client-types/src/lib/models/StoreReturnReasonsListRes.ts index 5970bb496e..5ca67a4916 100644 --- a/packages/generated/client-types/src/lib/models/StoreReturnReasonsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreReturnReasonsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ReturnReason } from "./ReturnReason" +/** + * The list of return reasons. + */ export interface StoreReturnReasonsListRes { /** * An array of return reasons details. diff --git a/packages/generated/client-types/src/lib/models/StoreReturnReasonsRes.ts b/packages/generated/client-types/src/lib/models/StoreReturnReasonsRes.ts index 1a1d9d10fc..277f7a26ad 100644 --- a/packages/generated/client-types/src/lib/models/StoreReturnReasonsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreReturnReasonsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { ReturnReason } from "./ReturnReason" +/** + * The return reason's details. + */ export interface StoreReturnReasonsRes { /** * Return reason details. diff --git a/packages/generated/client-types/src/lib/models/StoreReturnsRes.ts b/packages/generated/client-types/src/lib/models/StoreReturnsRes.ts index 4e32e49a5a..14867f07a3 100644 --- a/packages/generated/client-types/src/lib/models/StoreReturnsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreReturnsRes.ts @@ -6,6 +6,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { Return } from "./Return" import type { ReturnItem } from "./ReturnItem" +/** + * The return's details. + */ export interface StoreReturnsRes { /** * Return details. diff --git a/packages/generated/client-types/src/lib/models/StoreShippingOptionsListRes.ts b/packages/generated/client-types/src/lib/models/StoreShippingOptionsListRes.ts index 5c5c81205a..48934bfb06 100644 --- a/packages/generated/client-types/src/lib/models/StoreShippingOptionsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreShippingOptionsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedShippingOption } from "./PricedShippingOption" +/** + * The list of shipping options. + */ export interface StoreShippingOptionsListRes { /** * An array of shipping options details. diff --git a/packages/generated/client-types/src/lib/models/StoreSwapsRes.ts b/packages/generated/client-types/src/lib/models/StoreSwapsRes.ts index 532d5b861d..e800556b65 100644 --- a/packages/generated/client-types/src/lib/models/StoreSwapsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreSwapsRes.ts @@ -8,6 +8,9 @@ import type { LineItem } from "./LineItem" import type { Return } from "./Return" import type { Swap } from "./Swap" +/** + * The swap's details. + */ export interface StoreSwapsRes { /** * Swap details. diff --git a/packages/generated/client-types/src/lib/models/StoreVariantsListRes.ts b/packages/generated/client-types/src/lib/models/StoreVariantsListRes.ts index ca713c3bd4..65e99145ea 100644 --- a/packages/generated/client-types/src/lib/models/StoreVariantsListRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreVariantsListRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedVariant } from "./PricedVariant" +/** + * The list of product variants. + */ export interface StoreVariantsListRes { /** * An array of product variant descriptions. diff --git a/packages/generated/client-types/src/lib/models/StoreVariantsRes.ts b/packages/generated/client-types/src/lib/models/StoreVariantsRes.ts index 6d766ea48a..dc6287fe5f 100644 --- a/packages/generated/client-types/src/lib/models/StoreVariantsRes.ts +++ b/packages/generated/client-types/src/lib/models/StoreVariantsRes.ts @@ -5,6 +5,9 @@ import { SetRelation, Merge } from "../core/ModelUtils" import type { PricedVariant } from "./PricedVariant" +/** + * The product variant's details. + */ export interface StoreVariantsRes { /** * Product variant description. diff --git a/packages/generated/client-types/src/lib/models/VariantInventory.ts b/packages/generated/client-types/src/lib/models/VariantInventory.ts index 1838165b7a..22dfa305cf 100644 --- a/packages/generated/client-types/src/lib/models/VariantInventory.ts +++ b/packages/generated/client-types/src/lib/models/VariantInventory.ts @@ -15,7 +15,7 @@ export interface VariantInventory { */ inventory: ResponseInventoryItem /** - * An array of details about the variant's inventory availability in sales channels. + * Details about the variant's inventory availability in sales channels. */ sales_channel_availability: Array<{ /** diff --git a/packages/medusa-js/src/request.ts b/packages/medusa-js/src/request.ts index 9f168c7b37..525e682374 100644 --- a/packages/medusa-js/src/request.ts +++ b/packages/medusa-js/src/request.ts @@ -20,6 +20,14 @@ export interface Config { customHeaders?: Record } +/** + * @interface + * + * Options to pass to requests sent to custom API Routes + * + * @prop timeout - The number of milliseconds before the request times out. + * @prop numberOfRetries - The number of times to retry a request before failing. + */ export interface RequestOptions { timeout?: number numberOfRetries?: number diff --git a/packages/medusa-js/src/resources/addresses.ts b/packages/medusa-js/src/resources/addresses.ts index a0440d359e..8223871df5 100644 --- a/packages/medusa-js/src/resources/addresses.ts +++ b/packages/medusa-js/src/resources/addresses.ts @@ -6,12 +6,39 @@ import { import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to Address API Routes part of the [Store Customer API Routes](https://docs.medusajs.com/api/store#customers_postcustomers). All its method + * are available in the JS Client under the `medusa.customers.addresses` property. + * + * All methods in this class require {@link AuthResource.authenticate | customer authentication}. + */ class AddressesResource extends BaseResource { /** - * Adds an address to a customers saved addresses - * @param {StorePostCustomersCustomerAddressesReq} payload contains information to create an address - * @param customHeaders - * @return {ResponsePromise} + * Add an address to the logged-in customer's saved addresses. + * @param {StorePostCustomersCustomerAddressesReq} payload - The address to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details, including the customer's addresses in the `shipping_addresses` attribute. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.addresses.addAddress({ + * address: { + * first_name: "Celia", + * last_name: "Schumm", + * address_1: "225 Bednar Curve", + * city: "Danielville", + * country_code: "US", + * postal_code: "85137", + * phone: "981-596-6748 x90188", + * company: "Wyman LLC", + * province: "Georgia", + * } + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ addAddress( payload: StorePostCustomersCustomerAddressesReq, @@ -22,10 +49,19 @@ class AddressesResource extends BaseResource { } /** - * Deletes an address of a customer - * @param {string} address_id id of the address to delete - * @param customHeaders - * @return {ResponsePromise} + * Delete an address of the logged-in customer. + * @param {string} address_id - The ID of the address to delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details, including the customer's addresses in the `shipping_addresses` attribute. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.addresses.deleteAddress(addressId) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ deleteAddress( address_id: string, @@ -36,11 +72,22 @@ class AddressesResource extends BaseResource { } /** - * Update an address of a customer - * @param {string} address_id id of customer - * @param {StorePostCustomersCustomerAddressesAddressReq} payload address update - * @param customHeaders - * @return {StoreCustomersRes} + * Update an address of the logged-in customer. + * @param {string} address_id - The address's ID. + * @param {StorePostCustomersCustomerAddressesAddressReq} payload - The attributes to update in the address. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details, including the customer's addresses in the `shipping_addresses` attribute. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.addresses.updateAddress(addressId, { + * first_name: "Gina" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ updateAddress( address_id: string, diff --git a/packages/medusa-js/src/resources/admin/auth.ts b/packages/medusa-js/src/resources/admin/auth.ts index 48e1818453..1039b65636 100644 --- a/packages/medusa-js/src/resources/admin/auth.ts +++ b/packages/medusa-js/src/resources/admin/auth.ts @@ -3,12 +3,31 @@ import { ResponsePromise } from "../../typings" import JwtTokenManager from "../../jwt-token-manager" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Auth API Routes](https://docs.medusajs.com/api/admin#auth_getauth). All its method + * are available in the JS Client under the `medusa.admin.auth` property. + * + * The methods in this class allow admin users to manage their session, such as login or log out. + * You can send authenticated requests for an admin user either using the Cookie header, their API token, or the JWT Token. + * When you log the admin user in using the {@link createSession} method, the JS client will automatically attach the + * cookie header in all subsequent requests. + * + * Related Guide: [How to implement user profiles](https://docs.medusajs.com/modules/users/admin/manage-profile). + */ class AdminAuthResource extends BaseResource { /** - * @description Retrieves an authenticated session - * Usually used to check if authenticated session is alive. - * @param customHeaders - * @return {ResponsePromise} + * Get the currently logged in user's details. Can also be used to check if there is an authenticated user. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the logged-in user's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.auth.getSession() + * .then(({ user }) => { + * console.log(user.id); + * }) */ getSession( customHeaders: Record = {} @@ -18,9 +37,16 @@ class AdminAuthResource extends BaseResource { } /** - * @description destroys an authenticated session - * @param customHeaders - * @return {ResponsePromise} + * Log out the user and remove their authentication session. This will only work if you're using Cookie session for authentication. If the API token is still passed in the header, + * the user is still authorized to perform admin functionalities in other API Routes. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when user is logged out successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in + * medusa.admin.auth.deleteSession() */ deleteSession( customHeaders: Record = {} @@ -30,10 +56,21 @@ class AdminAuthResource extends BaseResource { } /** - * @description Creates an authenticated session - * @param {AdminPostAuthReq} payload - * @param customHeaders - * @return {ResponsePromise} + * Log a User in using their credentials. If the user is authenticated successfully, the cookie is automatically attached to subsequent requests sent with the JS Client. + * @param {AdminPostAuthReq} payload - The credentials of the user. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the user's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.admin.AdminAuthResource.createSession({ + * email: "user@example.com", + * password: "supersecret" + * }) + * .then(({ user }) => { + * console.log(user.id); + * }) */ createSession( payload: AdminPostAuthReq, @@ -44,10 +81,21 @@ class AdminAuthResource extends BaseResource { } /** - * @description Retrieves a new JWT access token - * @param {AdminPostAuthReq} payload - * @param customHeaders - * @return {ResponsePromise} + * Authenticate the user and retrieve a JWT token to use for subsequent authenticated requests. + * @param {AdminPostAuthReq} payload - The credentials of the user. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the access token of the user, if they're authenticated successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.admin.auth.getToken({ + * email: 'user@example.com', + * password: 'supersecret' + * }) + * .then(({ access_token }) => { + * console.log(access_token); + * }) */ getToken( payload: AdminPostAuthReq, diff --git a/packages/medusa-js/src/resources/admin/batch-jobs.ts b/packages/medusa-js/src/resources/admin/batch-jobs.ts index 413472a554..80fb2f04f9 100644 --- a/packages/medusa-js/src/resources/admin/batch-jobs.ts +++ b/packages/medusa-js/src/resources/admin/batch-jobs.ts @@ -9,7 +9,38 @@ import { ResponsePromise } from "../../typings" import BaseResource from "../base" import { stringifyNullProperties } from "../../utils" +/** + * This class is used to send requests to [Admin Batch Job API Routes](https://docs.medusajs.com/api/admin#batch-jobs). All its method + * are available in the JS Client under the `medusa.admin.batchJobs` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A batch job is a task that is performed by the Medusa backend asynchronusly. For example, the Import Product feature is implemented using batch jobs. + * The methods in this class allow admins to manage the batch jobs and their state. + * + * Related Guide: [How to import products](https://docs.medusajs.com/modules/products/admin/import-products). + */ class AdminBatchJobsResource extends BaseResource { + + /** + * Create a Batch Job to be executed asynchronously in the Medusa backend. If `dry_run` is set to `true`, the batch job will not be executed until the it is confirmed, + * which can be done using the {@link confirm} method. + * @param payload - The data of the batch job to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the batch job's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.create({ + * type: 'product-export', + * context: {}, + * dry_run: false + * }).then((({ batch_job }) => { + * console.log(batch_job.id); + * }) + */ create( payload: AdminPostBatchesReq, customHeaders: Record = {} @@ -18,6 +49,55 @@ class AdminBatchJobsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Retrieve a list of Batch Jobs. The batch jobs can be filtered by fields such as `type` or `confirmed_at`. The batch jobs can also be sorted or paginated. + * @param {AdminGetBatchParams} query - Filters and pagination configurations to apply on the retrieved batch jobs. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The list of batch jobs with pagination fields. + * + * @example + * To list batch jobs: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.list() + * .then(({ batch_jobs, limit, offset, count }) => { + * console.log(batch_jobs.length) + * }) + * ``` + * + * To specify relations that should be retrieved within the batch jobs: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.list({ + * expand: "created_by_user" + * }) + * .then(({ batch_jobs, limit, offset, count }) => { + * console.log(batch_jobs.length) + * }) + * ``` + * + * By default, only the first `10` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.list({ + * expand: "created_by_user", + * limit, + * offset + * }) + * .then(({ batch_jobs, limit, offset, count }) => { + * console.log(batch_jobs.length) + * }) + * ``` + */ list( query?: AdminGetBatchParams, customHeaders: Record = {} @@ -32,6 +112,21 @@ class AdminBatchJobsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Mark a batch job as canceled. When a batch job is canceled, the processing of the batch job doesn’t automatically stop. + * @param {string} batchJobId - The ID of the batch job. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the batch job's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.cancel(batchJobId) + * .then(({ batch_job }) => { + * console.log(batch_job.id); + * }) + */ cancel( batchJobId: string, customHeaders: Record = {} @@ -40,6 +135,21 @@ class AdminBatchJobsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * When a batch job is created, it's not executed automatically if `dry_run` is set to `true`. This method confirms that the batch job should be executed. + * @param {string} batchJobId - The ID of the batch job. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the batch job's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.confirm(batchJobId) + * .then(({ batch_job }) => { + * console.log(batch_job.id); + * }) + */ confirm( batchJobId: string, customHeaders: Record = {} @@ -48,6 +158,21 @@ class AdminBatchJobsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Retrieve the details of a batch job. + * @param {string} batchJobId - The ID of the batch job. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the batch job's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.batchJobs.retrieve(batchJobId) + * .then(({ batch_job }) => { + * console.log(batch_job.id); + * }) + */ retrieve( batchJobId: string, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/collections.ts b/packages/medusa-js/src/resources/admin/collections.ts index 8879af679a..4e8828f395 100644 --- a/packages/medusa-js/src/resources/admin/collections.ts +++ b/packages/medusa-js/src/resources/admin/collections.ts @@ -13,12 +13,31 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Product Collection API Routes](https://docs.medusajs.com/api/admin#product-collections). All its method + * are available in the JS Client under the `medusa.admin.collections` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A product collection is used to organize products for different purposes such as marketing or discount purposes. For example, you can create a Summer Collection. + */ class AdminCollectionsResource extends BaseResource { /** - * @description Creates a collection. - * @param payload - * @param customHeaders - * @returns Created collection. + * Create a product collection. + * @param {AdminPostCollectionsReq} payload - The data of the product collection to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the created product collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.create({ + * title: "New Collection" + * }) + * .then(({ collection }) => { + * console.log(collection.id); + * }) */ create( payload: AdminPostCollectionsReq, @@ -29,11 +48,22 @@ class AdminCollectionsResource extends BaseResource { } /** - * @description Updates a collection - * @param id id of the collection to update. - * @param payload update to apply to collection. - * @param customHeaders - * @returns the updated collection. + * Update a product collection's details. + * @param {string} id - The ID of the product collection. + * @param {AdminPostCollectionsCollectionReq} payload - The data to update in the product collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.update(collectionId, { + * title: "New Collection" + * }) + * .then(({ collection }) => { + * console.log(collection.id); + * }) */ update( id: string, @@ -45,10 +75,19 @@ class AdminCollectionsResource extends BaseResource { } /** - * @description deletes a collection - * @param id id of collection to delete. - * @param customHeaders - * @returns Deleted response + * Delete a product collection. This does not delete associated products. + * @param {string} id - The ID of the product collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.delete(collectionId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -59,10 +98,19 @@ class AdminCollectionsResource extends BaseResource { } /** - * @description get a collection - * @param id id of the collection to retrieve. - * @param customHeaders - * @returns the collection with the given id + * Retrieve a product collection by its ID. The products associated with it are expanded and returned as well. + * @param {string} id - The ID of the product collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.retrieve(collectionId) + * .then(({ collection }) => { + * console.log(collection.id); + * }) */ retrieve( id: string, @@ -73,10 +121,38 @@ class AdminCollectionsResource extends BaseResource { } /** - * @description Lists collections matching a query - * @param query Query for searching collections - * @param customHeaders - * @returns a list of collections matching the query. + * Retrieve a list of product collections. The product collections can be filtered by fields such as `handle` or `title`. The collections can also be sorted or paginated. + * @param {AdminGetCollectionsParams} query - Filters and pagination configurations to apply on the retrieved product collections. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product collections with pagination fields. + * + * @example + * To list product collections: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.list() + * .then(({ collections, limit, offset, count }) => { + * console.log(collections.length); + * }) + * ``` + * + * By default, only the first `10` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.list({ + * limit, + * offset + * }) + * .then(({ collections, limit, offset, count }) => { + * console.log(collections.length); + * }) + * ``` */ list( query?: AdminGetCollectionsParams, @@ -93,10 +169,25 @@ class AdminCollectionsResource extends BaseResource { } /** - * @description Updates products associated with a Product Collection - * @param id the id of the Collection - * @param payload - an object which contains an array of Product IDs to add to the Product Collection - * @param customHeaders + * Add products to collection. + * @param {string} id - The ID of the product collection. + * @param {AdminPostProductsToCollectionReq} payload - The products to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.addProducts(collectionId, { + * product_ids: [ + * productId1, + * productId2 + * ] + * }) + * .then(({ collection }) => { + * console.log(collection.products) + * }) */ addProducts( id: string, @@ -108,10 +199,25 @@ class AdminCollectionsResource extends BaseResource { } /** - * @description Removes products associated with a Product Collection - * @param id - the id of the Collection - * @param payload - an object which contains an array of Product IDs to add to the Product Collection - * @param customHeaders + * Remove a list of products from a collection. This would not delete the product, only the association between the product and the collection. + * @param {string} id - the ID of the product collection + * @param {AdminDeleteProductsFromCollectionReq} payload - The products to remove from the collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.collections.removeProducts(collectionId, { + * product_ids: [ + * productId1, + * productId2 + * ] + * }) + * .then(({ id, object, removed_products }) => { + * console.log(removed_products) + * }) */ removeProducts( id: string, diff --git a/packages/medusa-js/src/resources/admin/currencies.ts b/packages/medusa-js/src/resources/admin/currencies.ts index 76ba922018..b0ddefebd3 100644 --- a/packages/medusa-js/src/resources/admin/currencies.ts +++ b/packages/medusa-js/src/resources/admin/currencies.ts @@ -8,14 +8,51 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Currency API Routes](https://docs.medusajs.com/api/admin#currencies). All its method + * are available in the JS Client under the `medusa.admin.currencies` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A store can use unlimited currencies, and each region must be associated with at least one currency. + * Currencies are defined within the Medusa backend. The methods in this class allow admins to list and update currencies. + * + * Related Guide: [How to manage currencies](https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies). + */ class AdminCurrenciesResource extends BaseResource { /** - * @description Lists currencies. - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `tax_inclusive_pricing` in your medusa backend project. - * @param payload optional - * @param customHeaders - * @returns the list of currencies as well as the pagination properties. + * Retrieve a list of currencies. The currencies can be filtered by fields such as `code`. The currencies can also be sorted or paginated. + * @param {AdminGetCurrenciesParams} query - Filters and pagination configurations to apply on retrieved currencies. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of currencies with pagination fields. + * + * @example + * To list currencies: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.currencies.list() + * .then(({ currencies, count, offset, limit }) => { + * console.log(currencies.length); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.currencies.list({ + * limit, + * offset + * }) + * .then(({ currencies, count, offset, limit }) => { + * console.log(currencies.length); + * }) + * ``` */ list( query?: AdminGetCurrenciesParams, @@ -32,13 +69,22 @@ class AdminCurrenciesResource extends BaseResource { } /** - * @description Updates a currency - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `tax_inclusive_pricing` in your medusa backend project. - * @param code code of the currency to update. - * @param payload update to apply to currency. - * @param customHeaders - * @returns the updated currency. + * Update a Currency's details. + * @param {string} code - The code of the currency to update. + * @param {AdminPostCurrenciesCurrencyReq} payload - The attributes to update in the currency. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the currency's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.currencies.update(code, { + * includes_tax: true + * }) + * .then(({ currency }) => { + * console.log(currency.code); + * }) */ update( code: string, diff --git a/packages/medusa-js/src/resources/admin/custom.ts b/packages/medusa-js/src/resources/admin/custom.ts index 50dc910f02..1d96ce9a09 100644 --- a/packages/medusa-js/src/resources/admin/custom.ts +++ b/packages/medusa-js/src/resources/admin/custom.ts @@ -4,7 +4,34 @@ import { ResponsePromise } from "../../typings" import { createAdminPath } from "../../utils" import BaseResource from "../base" +/** + * This class is used to send requests custom API Routes. All its method + * are available in the JS Client under the `medusa.admin.custom` property. + */ class AdminCustomResource extends BaseResource { + /** + * Send a `GET` request to a custom API Route. The method accepts a tuple of type parameters: the first `TQuery` is the type of accepted query parameters, + * which defaults to `Record`; the second `TResponse` is the type of response, which defaults to `any`. + * @param {string} path - The path of the custom API Route. + * @param {TQuery} query - Query path parameters to pass in the request. + * @param {RequestOptions} options - Configurations to apply on the request. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The response data. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * type PostsResponse = { + * posts: Post[] + * } + * // must be previously logged in or use api token + * medusa.admin.custom.get, PostsResponse>( + * "/blog/posts" + * ) + * .then(({ posts }) => { + * console.log(posts.length); + * }) + */ get, TResponse = any>( path: string, query?: TQuery, @@ -27,6 +54,35 @@ class AdminCustomResource extends BaseResource { ) } + /** + * Send a `POST` request to a custom API Route. The method accepts a tuple of type parameters: the first `TPayload` is the type of accepted body parameters, + * which defaults to `Record`; the second `TResponse` is the type of response, which defaults to `any`. + * @param {string} path - The path of the custom API Route. + * @param {TPayload} payload - Body parameters to pass in the request. + * @param {RequestOptions} options - Configurations to apply on the request. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The response data. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * type PostRequest = { + * title: string + * } + * type PostResponse = { + * post: Post + * } + * // must be previously logged in or use api token + * medusa.admin.custom.post( + * "/blog/posts", + * { + * title: "My post", + * } + * ) + * .then(({ post }) => { + * console.log(post.id); + * }) + */ post, TResponse = any>( path: string, payload?: TPayload, @@ -44,6 +100,24 @@ class AdminCustomResource extends BaseResource { ) } + /** + * Send a `DELETE` request to a custom API Route. The method accepts a type parameters `TResponse` indicating the type of response, which defaults to `any`. + * @param {string} path - The path of the custom API Route. + * @param {RequestOptions} options - Configurations to apply on the request. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The response data. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.custom.delete( + * `/blog/posts/${postId}` + * ) + * .then(() => { + * // deleted successfully + * }) + */ delete( path: string, options?: RequestOptions, diff --git a/packages/medusa-js/src/resources/admin/customer-groups.ts b/packages/medusa-js/src/resources/admin/customer-groups.ts index 59815b2b42..dface26da2 100644 --- a/packages/medusa-js/src/resources/admin/customer-groups.ts +++ b/packages/medusa-js/src/resources/admin/customer-groups.ts @@ -16,12 +16,34 @@ import qs from "qs" import BaseResource from "../base" import { ResponsePromise } from "../.." +/** + * This class is used to send requests to [Admin Customer Group API Routes](https://docs.medusajs.com/api/admin#customer-groups). All its method + * are available in the JS Client under the `medusa.admin.customerGroups` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Customer Groups can be used to organize customers that share similar data or attributes into dedicated groups. + * This can be useful for different purposes such as setting a different price for a specific customer group. + * + * Related Guide: [How to manage customer groups](https://docs.medusajs.com/modules/customers/admin/manage-customer-groups). + */ class AdminCustomerGroupsResource extends BaseResource { /** * Create a customer group. - * - * @param payload - customer group info - * @param customHeaders + * @param {AdminPostCustomerGroupsReq} payload - The data of the customer group to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer group's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.create({ + * name: "VIP" + * }) + * .then(({ customer_group }) => { + * console.log(customer_group.id); + * }) */ create( payload: AdminPostCustomerGroupsReq, @@ -32,11 +54,20 @@ class AdminCustomerGroupsResource extends BaseResource { } /** - * Retrieves a customer group. - * - * @param id - customer group id - * @param query - pass query options such as "expand", "fields" etc. - * @param customHeaders + * Retrieve a customer group by its ID. You can expand the customer group's relations or select the fields that should be returned. + * @param {string} id - The ID of the customer group. + * @param {AdminGetCustomerGroupsGroupParams} query - Configurations to apply on the retrieved customer group. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer group's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.retrieve(customerGroupId) + * .then(({ customer_group }) => { + * console.log(customer_group.id); + * }) */ retrieve( id: string, @@ -53,11 +84,11 @@ class AdminCustomerGroupsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } /** - * Updates a customer group - * - * @param id - customer group id - * @param payload - data to update customer group with - * @param customHeaders + * Update a customer group's details. + * @param {string} id - The ID of the customer group. + * @param {AdminPostCustomerGroupsGroupReq} payload - The attributes to update in the customer group. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer group's details. */ update( id: string, @@ -69,10 +100,19 @@ class AdminCustomerGroupsResource extends BaseResource { } /** - * Deletes a customer group. - * - * @param id - id of the customer group - * @param customHeaders + * Delete a customer group. This doesn't delete the customers associated with the customer group. + * @param {string} id - The ID of the customer group. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.delete(customerGroupId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -83,10 +123,53 @@ class AdminCustomerGroupsResource extends BaseResource { } /** - * Lists customer groups. - * - * @param query optional - * @param customHeaders + * Retrieve a list of customer groups. The customer groups can be filtered by fields such as `name` or `id`. The customer groups can also be sorted or paginated. + * @param {AdminGetCustomerGroupsParams} query - Filters and pagination configurations to apply on the retrieved customer groups. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of customer groups with pagination fields. + * + * @example + * To list customer groups: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.list() + * .then(({ customer_groups, limit, offset, count }) => { + * console.log(customer_groups.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the customer groups: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.list({ + * expand: "customers" + * }) + * .then(({ customer_groups, limit, offset, count }) => { + * console.log(customer_groups.length); + * }) + * ``` + * + * By default, only the first `10` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.list({ + * "expand": "customers", + * limit, + * offset + * }) + * .then(({ customer_groups, limit, offset, count }) => { + * console.log(customer_groups.length); + * }) + * ``` */ list( query?: AdminGetCustomerGroupsParams, @@ -103,11 +186,11 @@ class AdminCustomerGroupsResource extends BaseResource { } /** - * Add multiple customers to a customer group. - * - * @param id - customer group id - * @param payload - an object which contains an array of customer ids which will be added to the group - * @param customHeaders + * Add a list of customers to a customer group. + * @param {string} id - The ID of the customer group. + * @param {AdminPostCustomerGroupsGroupCustomersBatchReq} payload - The customers to add to the customer group. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer group's details. */ addCustomers( id: string, @@ -119,11 +202,26 @@ class AdminCustomerGroupsResource extends BaseResource { } /** - * Remove multiple customers from a customer group. - * - * @param id - customer group id - * @param payload - an object which contains an array of customers ids which will be removed from the group - * @param customHeaders + * Remove a list of customers from a customer group. This doesn't delete the customer, only the association between the customer and the customer group. + * @param {string} id - The ID of the customer group. + * @param {AdminDeleteCustomerGroupsGroupCustomerBatchReq} payload - The customers to remove from the customer group. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer group's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.removeCustomers(customerGroupId, { + * customer_ids: [ + * { + * id: customerId + * } + * ] + * }) + * .then(({ customer_group }) => { + * console.log(customer_group.id); + * }) */ removeCustomers( id: string, @@ -135,11 +233,20 @@ class AdminCustomerGroupsResource extends BaseResource { } /** - * List and count customers that belong to provided customer groups. - * - * @param id - customer group id - * @param query - params for filtering customers - * @param customHeaders + * Retrieve a list of customers in a customer group. The customers can be filtered by the `q` field. The customers can also be paginated. + * @param {string} id - The ID of the customer group. + * @param {AdminGetCustomersParams} query - Filters and pagination configurations to apply on the retrieved customers. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of customers with pagination fields. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customerGroups.listCustomers(customerGroupId) + * .then(({ customers }) => { + * console.log(customers.length); + * }) */ listCustomers( id: string, diff --git a/packages/medusa-js/src/resources/admin/customers.ts b/packages/medusa-js/src/resources/admin/customers.ts index 2721fcd455..264ca86814 100644 --- a/packages/medusa-js/src/resources/admin/customers.ts +++ b/packages/medusa-js/src/resources/admin/customers.ts @@ -9,11 +9,36 @@ import qs from "qs" import { ResponsePromise } from "../.." import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Customer API Routes](https://docs.medusajs.com/api/admin#customers). All its method + * are available in the JS Client under the `medusa.admin.customers` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Customers can either be created when they register through the {@link CustomersResource.create} method, or created by the admin using the {@link create} method. + * + * Related Guide: [How to manage customers](https://docs.medusajs.com/modules/customers/admin/manage-customers). + */ class AdminCustomersResource extends BaseResource { /** - * Creates a customer - * @param payload information of customer - * @param customHeaders + * Create a customer as an admin. + * @param {AdminPostCustomersReq} payload - The customer to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customers.create({ + * email: "user@example.com", + * first_name: "Caterina", + * last_name: "Yost", + * password: "supersecret" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ create( payload: AdminPostCustomersReq, @@ -24,10 +49,22 @@ class AdminCustomersResource extends BaseResource { } /** - * Updates a customer - * @param id customer id - * @param payload data to update customer with - * @param customHeaders + * Update a customer's details. + * @param {string} id - The customer's ID. + * @param {AdminPostCustomersCustomerReq} payload - The attributes to update in the customer. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customers.update(customerId, { + * first_name: "Dolly" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ update( id: string, @@ -39,9 +76,19 @@ class AdminCustomersResource extends BaseResource { } /** - * Retrieves a customer - * @param id customer id - * @param customHeaders + * Retrieve the details of a customer. + * @param {string} id - The customer's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customers.retrieve(customerId) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ retrieve( id: string, @@ -52,9 +99,53 @@ class AdminCustomersResource extends BaseResource { } /** - * Lists customers - * @param query optional - * @param customHeaders + * Retrieve a list of Customers. The customers can be filtered by fields such as `q` or `groups`. The customers can also be paginated. + * @param {AdminGetCustomersParams} query - Filters and pagination configurations to apply on the retrieved customers. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of customers with pagination fields. + * + * @example + * To list customers: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customers.list() + * .then(({ customers, limit, offset, count }) => { + * console.log(customers.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the customers: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customers.list({ + * expand: "billing_address" + * }) + * .then(({ customers, limit, offset, count }) => { + * console.log(customers.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.customers.list({ + * expand: "billing_address", + * limit, + * offset + * }) + * .then(({ customers, limit, offset, count }) => { + * console.log(customers.length); + * }) + * ``` */ list( query?: AdminGetCustomersParams, diff --git a/packages/medusa-js/src/resources/admin/discounts.ts b/packages/medusa-js/src/resources/admin/discounts.ts index d05eab1860..ac22278790 100644 --- a/packages/medusa-js/src/resources/admin/discounts.ts +++ b/packages/medusa-js/src/resources/admin/discounts.ts @@ -20,9 +20,33 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Discount API Routes](https://docs.medusajs.com/api/admin#discounts). All its method + * are available in the JS Client under the `medusa.admin.discounts` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Admins can create discounts with conditions and rules, providing them with advanced settings for variety of cases. + * The methods in this class can be used to manage discounts, their conditions, resources, and more. + * + * Related Guide: [How to manage discounts](https://docs.medusajs.com/modules/discounts/admin/manage-discounts). + */ class AdminDiscountsResource extends BaseResource { /** - * @description Adds region to discount + * Add a Region to the list of Regions a Discount can be used in. + * @param {string} id - The discount's ID. + * @param {string} regionId - The ID of the region to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the discount's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.addRegion(discountId, regionId) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ addRegion( id: string, @@ -34,7 +58,30 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Creates discounts + * Create a discount with a given set of rules that defines how the discount is applied. + * @param {AdminPostDiscountsReq} payload - The discount to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the discount's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * import { AllocationType, DiscountRuleType } from "@medusajs/medusa" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.create({ + * code: "TEST", + * rule: { + * type: DiscountRuleType.FIXED, + * value: 10, + * allocation: AllocationType.ITEM + * }, + * regions: ["reg_XXXXXXXX"], + * is_dynamic: false, + * is_disabled: false + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ create( payload: AdminPostDiscountsReq, @@ -45,7 +92,22 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Updates discount + * Update a discount with a given set of rules that define how the discount is applied. + * @param {string} id - The discount's ID. + * @param {AdminPostDiscountsDiscountReq} payload - The attributes to update in the discount. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.update(discountId, { + * code: "TEST" + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ update( id: string, @@ -57,7 +119,23 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Creates a dynamic discount code + * Create a dynamic unique code that can map to a parent discount. This is useful if you want to automatically generate codes with the same rules and conditions. + * @param {string} id - The discount's ID. + * @param {AdminPostDiscountsDiscountDynamicCodesReq} payload - The dynamic code to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.createDynamicCode(discountId, { + * code: "TEST", + * usage_limit: 1 + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ createDynamicCode( id: string, @@ -69,7 +147,19 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Deletes a discount + * Delete a discount. Deleting the discount will make it unavailable for customers to use. + * @param {string} id - The discount's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the delete operation details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.delete(discountId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -80,7 +170,20 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Deletes a dynamic discount + * Delete a dynamic code from a discount. + * @param {string} id - The discount's ID. + * @param {string} code - The code of the dynamic code to delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.deleteDynamicCode(discountId, code) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ deleteDynamicCode( id: string, @@ -92,7 +195,19 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Retrieves a discount + * Retrieve a discount. + * @param {string} id - The discount's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.retrieve(discountId) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ retrieve( id: string, @@ -103,7 +218,19 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Retrieves a discount by code + * Retrieve a discount's details by its discount code. + * @param {string} code - The code of the discount. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.retrieveByCode(code) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ retrieveByCode( code: string, @@ -114,7 +241,53 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Lists discounts + * Retrieve a list of Discounts. The discounts can be filtered by fields such as `rule` or `is_dynamic`. The discounts can also be paginated. + * @param {AdminGetDiscountsParams} query - Filters and pagination configurations to apply on the retrieved discounts. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of discounts with pagination fields. + * + * @example + * To list discounts: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.list() + * .then(({ discounts, limit, offset, count }) => { + * console.log(discounts.id); + * }) + * ``` + * + * To specify relations that should be retrieved within the discounts: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.list({ + * expand: "rule" + * }) + * .then(({ discounts, limit, offset, count }) => { + * console.log(discounts.id); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.list({ + * expand: "rule", + * limit, + * offset + * }) + * .then(({ discounts, limit, offset, count }) => { + * console.log(discounts.id); + * }) + * ``` */ list( query?: AdminGetDiscountsParams, @@ -131,7 +304,20 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Removes a region from a discount + * Remove a Region from the list of Regions that a Discount can be used in. This does not delete a region, only the association between it and the discount. + * @param {string} id - The discount's ID. + * @param {string} regionId - The ID of the region to remove. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.removeRegion(discountId, regionId) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ removeRegion( id: string, @@ -143,7 +329,48 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description creates a discount condition + * Create a discount condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided in the `payload` parameter, + * based on the type of discount condition. For example, if the discount condition's type is `products`, the `products` field should be provided in the `payload` parameter. + * @param {string} discountId - The discount's ID. + * @param {AdminPostDiscountsDiscountConditions} payload - The discount condition to create. + * @param {AdminPostDiscountsDiscountConditionsParams} query - Configurations to apply on the returned discount. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * To create a condition in a discount: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * import { DiscountConditionOperator } from "@medusajs/medusa" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.createCondition(discountId, { + * operator: DiscountConditionOperator.IN, + * products: [productId] + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) + * ``` + * + * To specify relations that should be retrieved as part of the response: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * import { DiscountConditionOperator } from "@medusajs/medusa" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.createCondition(discountId, { + * operator: DiscountConditionOperator.IN, + * products: [productId] + * }, { + * expand: "rule" + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) + * ``` */ createCondition( discountId: string, @@ -162,7 +389,49 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Updates a discount condition + * Update a discount condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided in the `payload` parameter, + * based on the type of discount condition. For example, if the discount condition's type is `products`, the `products` field should be provided in the `payload` parameter. + * @param {string} discountId - The discount's ID. + * @param {string} conditionId - The ID of the discount condition. + * @param {AdminPostDiscountsDiscountConditionsCondition} payload - The attributes to update in the discount condition. + * @param {AdminPostDiscountsDiscountConditionsConditionParams} query - Configurations to apply on the returned discount. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * To update a condition in a discount: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.updateCondition(discountId, conditionId, { + * products: [ + * productId + * ] + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) + * ``` + * + * To specify relations that should be retrieved as part of the response: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.updateCondition(discountId, conditionId, { + * products: [ + * productId + * ] + * }, { + * expand: "rule" + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) + * ``` */ updateCondition( discountId: string, @@ -182,7 +451,20 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Removes a condition from a discount + * Delete a discount condition. This doesn't delete resources associated to the discount condition. + * @param {string} discountId - The discount's ID. + * @param {string} conditionId - The ID of the discount condition. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.deleteCondition(discountId, conditionId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ deleteCondition( discountId: string, @@ -194,7 +476,39 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Gets a condition from a discount + * Retrieve a Discount Condition's details. + * @param {string} discountId - The ID of the discount that the condition belongs to. + * @param {string} conditionId - The ID of the discount condition. + * @param {AdminGetDiscountsDiscountConditionsConditionParams} query - Configurations to apply on the retrieved discount condition. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the discount condition details. + * + * @example + * A simple example that retrieves a discount condition by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.getCondition(discountId, conditionId) + * .then(({ discount_condition }) => { + * console.log(discount_condition.id); + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.getCondition(discountId, conditionId, { + * expand: "discount_rule" + * }) + * .then(({ discount_condition }) => { + * console.log(discount_condition.id); + * }) + * ``` */ getCondition( discountId: string, @@ -213,7 +527,45 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Add a batch of items to a discount condition + * Add a batch of resources to a discount condition. The type of resource depends on the type of discount condition. For example, if the discount condition's type is `products`, + * the resources being added should be products. + * @param {string} discountId - The ID of the discount the condition belongs to. + * @param {string} conditionId - The ID of the discount condition. + * @param {AdminPostDiscountsDiscountConditionsConditionBatchReq} payload - The resources to add to the discount condition. + * @param {AdminPostDiscountsDiscountConditionsConditionBatchParams} query - Configurations to apply on the retrieved discount. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * To add resources to a discount condition: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.addConditionResourceBatch(discountId, conditionId, { + * resources: [{ id: itemId }] + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) + * ``` + * + * To specify relations to include in the returned discount: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.addConditionResourceBatch(discountId, conditionId, { + * resources: [{ id: itemId }] + * }, { + * expand: "rule" + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) + * ``` */ addConditionResourceBatch( discountId: string, @@ -233,7 +585,23 @@ class AdminDiscountsResource extends BaseResource { } /** - * @description Delete a batch of items from a discount condition + * Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, not the resource itself. + * @param {string} discountId - The ID of the discount the condition belongs to. + * @param {string} conditionId - The ID of the discount condition. + * @param {AdminDeleteDiscountsDiscountConditionsConditionBatchReq} payload - The resources to remove. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the discount. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.discounts.deleteConditionResourceBatch(discountId, conditionId, { + * resources: [{ id: itemId }] + * }) + * .then(({ discount }) => { + * console.log(discount.id); + * }) */ deleteConditionResourceBatch( discountId: string, diff --git a/packages/medusa-js/src/resources/admin/draft-orders.ts b/packages/medusa-js/src/resources/admin/draft-orders.ts index 28cecc3ced..7bdf20c971 100644 --- a/packages/medusa-js/src/resources/admin/draft-orders.ts +++ b/packages/medusa-js/src/resources/admin/draft-orders.ts @@ -13,9 +13,44 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Draft Order API Routes](https://docs.medusajs.com/api/admin#draft-orders). All its method + * are available in the JS Client under the `medusa.admin.draftOrders` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A draft order is an order created manually by the admin. It allows admins to create orders without direct involvement from the customer. + * + * Related Guide: [How to manage draft orders](https://docs.medusajs.com/modules/orders/admin/manage-draft-orders). + */ class AdminDraftOrdersResource extends BaseResource { /** - * @description Creates a draft order + * Create a Draft Order. A draft order is not transformed into an order until payment is captured. + * @param {AdminPostDraftOrdersReq} payload - The draft order to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the draft order's details + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.create({ + * email: "user@example.com", + * region_id, + * items: [ + * { + * quantity: 1 + * } + * ], + * shipping_methods: [ + * { + * option_id + * } + * ], + * }) + * .then(({ draft_order }) => { + * console.log(draft_order.id); + * }) */ create( payload: AdminPostDraftOrdersReq, @@ -25,7 +60,22 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Add line item to draft order + * Create a Line Item in the Draft Order. + * @param {string} id - The ID of the draft order. + * @param {AdminPostDraftOrdersDraftOrderLineItemsReq} payload - The line item to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the draft order's details + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.addLineItem(draftOrderId, { + * quantity: 1 + * }) + * .then(({ draft_order }) => { + * console.log(draft_order.id); + * }) */ addLineItem( id: string, @@ -37,7 +87,19 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Delete draft order + * Delete a Draft Order + * @param {string} id - The ID of the draft order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.delete(draftOrderId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -48,7 +110,20 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Remove line item + * Delete a Line Item from a Draft Order. + * @param {string} id - The ID of the draft order that the line item belongs to. + * @param {string} itemId - The ID of the line item to delete from the draft order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the draft order's details + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.removeLineItem(draftOrderId, itemId) + * .then(({ draft_order }) => { + * console.log(draft_order.id); + * }) */ removeLineItem( id: string, @@ -60,7 +135,19 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Retrieves a draft order + * Retrieve a Draft Order's details. + * @param {string} id - The ID of the draft order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the draft order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.retrieve(draftOrderId) + * .then(({ draft_order }) => { + * console.log(draft_order.id); + * }) */ retrieve( id: string, @@ -71,7 +158,38 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Lists draft orders + * Retrieve an list of Draft Orders. The draft orders can be filtered by parameters such as `query`. The draft orders can also paginated. + * @param {AdminGetDraftOrdersParams} query - Filters and pagination configurations to apply on the retrieved draft orders. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of draft orders with pagination fields. + * + * @example + * To list draft orders: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.list() + * .then(({ draft_orders, limit, offset, count }) => { + * console.log(draft_orders.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.list({ + * limit, + * offset + * }) + * .then(({ draft_orders, limit, offset, count }) => { + * console.log(draft_orders.length); + * }) + * ``` */ list( query?: AdminGetDraftOrdersParams, @@ -88,7 +206,20 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Mark a draft order as paid + * Capture the draft order's payment. This will also set the draft order's status to `completed` and create an order from the draft order. The payment is captured through Medusa's system payment, + * which is manual payment that isn't integrated with any third-party payment provider. It is assumed that the payment capturing is handled manually by the admin. + * @param {string} id - The ID of the draft order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the created order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.markPaid(draftOrderId) + * .then(({ order }) => { + * console.log(order.id); + * }) */ markPaid( id: string, @@ -99,7 +230,22 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Update draft order + * Update a Draft Order's details. + * @param {string} id - The ID of the draft order. + * @param {AdminPostDraftOrdersDraftOrderReq} payload - The attributes to update in the draft order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the draft order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.update(draftOrderId, { + * email: "user@example.com" + * }) + * .then(({ draft_order }) => { + * console.log(draft_order.id); + * }) */ update( id: string, @@ -111,7 +257,23 @@ class AdminDraftOrdersResource extends BaseResource { } /** - * @description Update draft order line item + * Update a Line Item in a Draft Order. + * @param {string} id - The ID of the draft order that the line item belongs to. + * @param {string} itemId - The ID of the line item to update. + * @param {AdminPostDraftOrdersDraftOrderLineItemsItemReq} payload - The attributes to update in the line item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the draft order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.draftOrders.updateLineItem(draftOrderId, lineId, { + * quantity: 1 + * }) + * .then(({ draft_order }) => { + * console.log(draft_order.id); + * }) */ updateLineItem( id: string, diff --git a/packages/medusa-js/src/resources/admin/gift-cards.ts b/packages/medusa-js/src/resources/admin/gift-cards.ts index b6373ed20e..ed07a80d5e 100644 --- a/packages/medusa-js/src/resources/admin/gift-cards.ts +++ b/packages/medusa-js/src/resources/admin/gift-cards.ts @@ -10,9 +10,34 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Gift Card API Routes](https://docs.medusajs.com/api/admin#gift-cards). All its method + * are available in the JS Client under the `medusa.admin.giftCards` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Admins can create gift cards and send them directly to customers, specifying options like their balance, region, and more. + * These gift cards are different than the saleable gift cards in a store, which are created and managed through {@link AdminProductsResource}. + * + * Related Guide: [How to manage gift cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards). + */ class AdminGiftCardsResource extends BaseResource { /** - * @description Creates a gift card + * Create a gift card that can redeemed by its unique code. The Gift Card is only valid within `1` region. + * @param {AdminPostGiftCardsReq} payload - The gift card to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the gift card's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.giftCards.create({ + * region_id + * }) + * .then(({ gift_card }) => { + * console.log(gift_card.id); + * }) */ create( payload: AdminPostGiftCardsReq, @@ -23,7 +48,22 @@ class AdminGiftCardsResource extends BaseResource { } /** - * @description Updates a gift card + * Update a gift card's details. + * @param {string} id - The ID of the gift card. + * @param {AdminPostGiftCardsGiftCardReq} payload - The attributes to update in the gift card. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the gift card's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.giftCards.update(giftCardId, { + * region_id + * }) + * .then(({ gift_card }) => { + * console.log(gift_card.id); + * }) */ update( id: string, @@ -35,7 +75,19 @@ class AdminGiftCardsResource extends BaseResource { } /** - * @description Deletes a gift card + * Delete a gift card. Once deleted, it can't be used by customers. + * @param {string} id - The ID of the gift card. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.giftCards.delete(giftCardId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -46,7 +98,19 @@ class AdminGiftCardsResource extends BaseResource { } /** - * @description Deletes a gift card + * Retrieve a gift card's details. + * @param {string} id - The ID of the gift card. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the gift card's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.giftCards.retrieve(giftCardId) + * .then(({ gift_card }) => { + * console.log(gift_card.id); + * }) */ retrieve( id: string, @@ -57,7 +121,38 @@ class AdminGiftCardsResource extends BaseResource { } /** - * @description Lists gift cards + * Retrieve a list of gift cards. The gift cards can be filtered by fields such as `q` passed in the `query` parameter. The gift cards can also paginated. + * @param {AdminGetGiftCardsParams} query - Filters and pagination configurations to apply on the retrieved gift cards. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of gift cards with pagination fields. + * + * @example + * To list gift cards: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.giftCards.list() + * .then(({ gift_cards, limit, offset, count }) => { + * console.log(gift_cards.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.giftCards.list({ + * limit, + * offset + * }) + * .then(({ gift_cards, limit, offset, count }) => { + * console.log(gift_cards.length); + * }) + * ``` */ list( query?: AdminGetGiftCardsParams, diff --git a/packages/medusa-js/src/resources/admin/index.ts b/packages/medusa-js/src/resources/admin/index.ts index 6734aee8ef..32785fc9b1 100644 --- a/packages/medusa-js/src/resources/admin/index.ts +++ b/packages/medusa-js/src/resources/admin/index.ts @@ -38,44 +38,162 @@ import AdminUploadsResource from "./uploads" import AdminUsersResource from "./users" import AdminVariantsResource from "./variants" +/** + * This class includes properties used to send requests to the [Admin API Routes](https://docs.medusajs.com/api/admin). All its properties + * are available in the JS Client under the `medusa.admin` property. + */ class Admin extends BaseResource { + /** + * An instance of {@link AdminAuthResource} used to send requests to [Admin Auth API Routes](https://docs.medusajs.com/api/admin#auth). + */ public auth = new AdminAuthResource(this.client) + /** + * An instance of {@link AdminBatchJobsResource} used to send requests to [Admin Batch Job API Routes](https://docs.medusajs.com/api/admin#batch-jobs). + */ public batchJobs = new AdminBatchJobsResource(this.client) + /** + * An instance of {@link AdminCustomersResource} used to send requests to [Admin Customer API Routes](https://docs.medusajs.com/api/admin#customers). + */ public customers = new AdminCustomersResource(this.client) + /** + * An instance of {@link AdminCustomerGroupsResource} used to send requests to [Admin Customer Group API Routes](https://docs.medusajs.com/api/admin#customer-groups). + */ public customerGroups = new AdminCustomerGroupsResource(this.client) + /** + * An instance of {@link AdminDiscountsResource} used to send requests to [Admin Discount API Routes](https://docs.medusajs.com/api/admin#discounts). + */ public discounts = new AdminDiscountsResource(this.client) + /** + * An instance of {@link AdminCurrenciesResource} used to send requests to [Admin Currency API Routes](https://docs.medusajs.com/api/admin#currencies_getcurrencies). + */ public currencies = new AdminCurrenciesResource(this.client) + /** + * An instance of {@link AdminCollectionsResource} used to send requests to [Admin Product Collection API Routes](https://docs.medusajs.com/api/admin#product-collections). + */ public collections = new AdminCollectionsResource(this.client) + /** + * An instance of {@link AdminDraftOrdersResource} used to send requests to [Admin Draft Order API Routes](https://docs.medusajs.com/api/admin#draft-orders). + */ public draftOrders = new AdminDraftOrdersResource(this.client) + /** + * An instance of {@link AdminGiftCardsResource} used to send requests to [Admin Gift Card API Routes](https://docs.medusajs.com/api/admin#gift-cards). + */ public giftCards = new AdminGiftCardsResource(this.client) + /** + * An instance of {@link AdminInvitesResource} used to send requests to [Admin Invite API Routes](https://docs.medusajs.com/api/admin#invites). + */ public invites = new AdminInvitesResource(this.client) + /** + * An instance of {@link AdminInventoryItemsResource} used to send requests to [Admin Inventory Item API Routes](https://docs.medusajs.com/api/admin#inventory-items). + */ public inventoryItems = new AdminInventoryItemsResource(this.client) + /** + * An instance of {@link AdminNotesResource} used to send requests to [Admin Note API Routes](https://docs.medusajs.com/api/admin#notes). + */ public notes = new AdminNotesResource(this.client) + /** + * An instance of {@link AdminPriceListResource} used to send requests to [Admin Price List API Routes](https://docs.medusajs.com/api/admin#price-lists). + */ public priceLists = new AdminPriceListResource(this.client) + /** + * An instance of {@link AdminProductsResource} used to send requests to [Admin Product API Routes](https://docs.medusajs.com/api/admin#products). + */ public products = new AdminProductsResource(this.client) + /** + * An instance of {@link AdminProductTagsResource} used to send requests to [Admin Product Tag API Routes](https://docs.medusajs.com/api/admin#product-tags). + */ public productTags = new AdminProductTagsResource(this.client) + /** + * An instance of {@link AdminProductTypesResource} used to send requests to [Admin Product Type API Routes](https://docs.medusajs.com/api/admin#product-types). + */ public productTypes = new AdminProductTypesResource(this.client) + /** + * An instance of {@link AdminUsersResource} used to send requests to [Admin User API Routes](https://docs.medusajs.com/api/admin#users). + */ public users = new AdminUsersResource(this.client) + /** + * An instance of {@link AdminReturnsResource} used to send requests to [Admin Return API Routes](https://docs.medusajs.com/api/admin#returns). + */ public returns = new AdminReturnsResource(this.client) + /** + * An instance of {@link AdminOrdersResource} used to send requests to [Admin Order API Routes](https://docs.medusajs.com/api/admin#orders). + */ public orders = new AdminOrdersResource(this.client) + /** + * An instance of {@link AdminOrderEditsResource} used to send requests to [Admin Order Edit API Routes](https://docs.medusajs.com/api/admin#order-edits). + */ public orderEdits = new AdminOrderEditsResource(this.client) + /** + * An instance of {@link AdminPublishableApiKeyResource} used to send requests to [Admin Publishable API Key API Routes](https://docs.medusajs.com/api/admin#publishable-api-keys). + */ public publishableApiKeys = new AdminPublishableApiKeyResource(this.client) + /** + * An instance of {@link AdminReturnReasonsResource} used to send requests to [Admin Return Reason API Routes](https://docs.medusajs.com/api/admin#return-reasons). + */ public returnReasons = new AdminReturnReasonsResource(this.client) + /** + * @props variants - An instance of {@link AdminVariantsResource} used to send requests to [Admin Product Variant API Routes](https://docs.medusajs.com/api/admin#product-variants). + */ public variants = new AdminVariantsResource(this.client) + /** + * An instance of {@link AdminSalesChannelsResource} used to send requests to [Admin Sales Channel API Routes](https://docs.medusajs.com/api/admin#sales-channels). + */ public salesChannels = new AdminSalesChannelsResource(this.client) + /** + * An instance of {@link AdminSwapsResource} used to send requests to [Admin Swap API Routes](https://docs.medusajs.com/api/admin#swaps). + */ public swaps = new AdminSwapsResource(this.client) + /** + * An instance of {@link AdminShippingProfilesResource} used to send requests to [Admin Shipping Profile API Routes](https://docs.medusajs.com/api/admin#shipping-profiles). + */ public shippingProfiles = new AdminShippingProfilesResource(this.client) + /** + * An instance of {@link AdminStockLocationsResource} used to send requests to [Admin Stock Location API Routes](https://docs.medusajs.com/api/admin#stock-locations). + */ public stockLocations = new AdminStockLocationsResource(this.client) + /** + * An instance of {@link AdminStoresResource} used to send requests to [Admin Store API Routes](https://docs.medusajs.com/api/admin#store). + */ public store = new AdminStoresResource(this.client) + /** + * An instance of {@link AdminShippingOptionsResource} used to send requests to [Admin Shipping Option API Routes](https://docs.medusajs.com/api/admin#shipping-options). + */ public shippingOptions = new AdminShippingOptionsResource(this.client) + /** + * An instance of {@link AdminRegionsResource} used to send requests to [Admin Region API Routes](https://docs.medusajs.com/api/admin#regions). + */ public regions = new AdminRegionsResource(this.client) + /** + * An instance of {@link AdminReservationsResource} used to send requests to [Admin Reservation API Routes](https://docs.medusajs.com/api/admin#reservations). + */ public reservations = new AdminReservationsResource(this.client) + /** + * An instance of {@link AdminNotificationsResource} used to send requests to [Admin Notification API Routes](https://docs.medusajs.com/api/admin#notifications). + */ public notifications = new AdminNotificationsResource(this.client) + /** + * An instance of {@link AdminTaxRatesResource} used to send requests to [Admin Tax Rate API Routes](https://docs.medusajs.com/api/admin#tax-rates). + */ public taxRates = new AdminTaxRatesResource(this.client) + /** + * An instance of {@link AdminUploadsResource} used to send requests to [Admin Upload API Routes](https://docs.medusajs.com/api/admin#uploads). + */ public uploads = new AdminUploadsResource(this.client) + /** + * An instance of {@link AdminPaymentCollectionsResource} used to send requests to [Admin Payment Collection API Routes](https://docs.medusajs.com/api/admin#payment-collections). + */ public paymentCollections = new AdminPaymentCollectionsResource(this.client) + /** + * An instance of {@link AdminPaymentsResource} used to send requests to [Admin Payment API Routes](https://docs.medusajs.com/api/admin#payments). + */ public payments = new AdminPaymentsResource(this.client) + /** + * An instance of {@link AdminProductCategoriesResource} used to send requests to [Admin Product Category API Routes](https://docs.medusajs.com/api/admin#product-categories). + */ public productCategories = new AdminProductCategoriesResource(this.client) + /** + * An instance of {@link AdminCustomResource} used to send requests to custom API Routes. + */ public custom = new AdminCustomResource(this.client) } @@ -91,6 +209,7 @@ export { AdminDiscountsResource, AdminDraftOrdersResource, AdminGiftCardsResource, + AdminInventoryItemsResource, AdminInvitesResource, AdminNotesResource, AdminNotificationsResource, @@ -102,6 +221,7 @@ export { AdminProductsResource, AdminPublishableApiKeyResource, AdminRegionsResource, + AdminReservationsResource, AdminReturnReasonsResource, AdminReturnsResource, AdminSalesChannelsResource, diff --git a/packages/medusa-js/src/resources/admin/inventory-item.ts b/packages/medusa-js/src/resources/admin/inventory-item.ts index c77223b28d..c839bdda7a 100644 --- a/packages/medusa-js/src/resources/admin/inventory-item.ts +++ b/packages/medusa-js/src/resources/admin/inventory-item.ts @@ -8,6 +8,7 @@ import { AdminInventoryItemsRes, AdminPostInventoryItemsInventoryItemReq, AdminPostInventoryItemsItemLocationLevelsLevelReq, + AdminPostInventoryItemsItemLocationLevelsParams, AdminPostInventoryItemsItemLocationLevelsReq, AdminPostInventoryItemsParams, AdminPostInventoryItemsReq, @@ -16,14 +17,36 @@ import { import BaseResource from "../base" import { ResponsePromise } from "../../typings" import qs from "qs" +import { AdminPostInventoryItemsInventoryItemParams } from "@medusajs/medusa" +import { AdminPostInventoryItemsItemLocationLevelsLevelParams } from "@medusajs/medusa" +/** + * This class is used to send requests to [Admin Inventory Item API Routes](https://docs.medusajs.com/api/admin#inventory-items). To use these API Routes, make sure to install the + * [@medusajs/inventory](https://docs.medusajs.com/modules/multiwarehouse/install-modules#inventory-module) module in your Medusa backend. All its method + * are available in the JS Client under the `medusa.admin.inventoryItems` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Inventory items, provided by the [Inventory Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), can be used to manage the inventory of saleable items in your store. + * + * Related Guide: [How to manage inventory items](https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items). + */ class AdminInventoryItemsResource extends BaseResource { /** - * Retrieve an Inventory Item - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description gets an Inventory Item - * @returns an Inventory Item + * Retrieve an Inventory Item's details. + * @param {string} inventoryItemId - The ID of the inventory item. + * @param {AdminGetInventoryItemsItemParams} query - Configurations applied on the retrieved inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The inventory item's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.retrieve(inventoryItemId) + * .then(({ inventory_item }) => { + * console.log(inventory_item.id); + * }) */ retrieve( inventoryItemId: string, @@ -41,16 +64,28 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Update an Inventory Item - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description updates an Inventory Item - * @returns the updated Inventory Item + * Update an Inventory Item's details. + * @param {string} inventoryItemId - The ID of the inventory item. + * @param {AdminPostInventoryItemsInventoryItemReq} payload - The attributes to update in the inventory item. + * @param {AdminPostInventoryItemsInventoryItemParams} query - Configurations to apply on the retrieved inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The inventory item's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.update(inventoryItemId, { + * origin_country: "US", + * }) + * .then(({ inventory_item }) => { + * console.log(inventory_item.id); + * }) */ update( inventoryItemId: string, payload: AdminPostInventoryItemsInventoryItemReq, - query?: AdminGetInventoryItemsItemParams, + query?: AdminPostInventoryItemsInventoryItemParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/inventory-items/${inventoryItemId}` @@ -64,11 +99,19 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Delete an Inventory Item - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description deletes an Inventory Item - * @returns the deleted Inventory Item + * Delete an Inventory Item. This does not delete the associated product variant. + * @param {string} inventoryItemId - The ID of the inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.delete(inventoryItemId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) */ delete( inventoryItemId: string, @@ -79,11 +122,22 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Create an Inventory Item - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description creates an Inventory Item - * @returns the created Inventory Item + * Create an Inventory Item for a product variant. + * @param {AdminPostInventoryItemsReq} payload - The inventory item to create. + * @param {AdminPostInventoryItemsParams} query - Configurations to apply on the retrieved inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The inventory item's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.create({ + * variant_id: "variant_123", + * }) + * .then(({ inventory_item }) => { + * console.log(inventory_item.id); + * }) */ create( payload: AdminPostInventoryItemsReq, @@ -101,11 +155,48 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Retrieve a list of Inventory Items - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description Retrieve a list of Inventory Items - * @returns the list of Inventory Items as well as the pagination properties + * Retrieve a list of inventory items. The inventory items can be filtered by fields such as `q` or `location_id` passed in the `query` parameter. + * The inventory items can also be paginated. + * @param {AdminGetInventoryItemsParams} query - Filters and pagination configurations applied on the retrieved inventory items. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The list of inventory items with pagination fields. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.list() + * .then(({ inventory_items, count, offset, limit }) => { + * console.log(inventory_items.length); + * }) + * + * @example + * To list inventory items: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.list() + * .then(({ inventory_items, count, offset, limit }) => { + * console.log(inventory_items.length); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.list({ + * limit, + * offset + * }) + * .then(({ inventory_items, count, offset, limit }) => { + * console.log(inventory_items.length); + * }) + * ``` */ list( query?: AdminGetInventoryItemsParams, @@ -122,17 +213,30 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Update an Inventory Item's stock level at a Stock Location - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description updates an Inventory Item - * @returns the updated Inventory Item + * Update a location level's details for a given inventory item. + * @param {string} inventoryItemId - The ID of the inventory item that the location level belongs to. + * @param {string} locationId - The ID of the location level to update. + * @param {AdminPostInventoryItemsItemLocationLevelsLevelReq} payload - The attributes to update in the location level. + * @param {AdminPostInventoryItemsItemLocationLevelsLevelParams} query - Configurations to apply on the returned inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} the inventory item's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.updateLocationLevel(inventoryItemId, locationId, { + * stocked_quantity: 15, + * }) + * .then(({ inventory_item }) => { + * console.log(inventory_item.id); + * }) */ updateLocationLevel( inventoryItemId: string, locationId: string, payload: AdminPostInventoryItemsItemLocationLevelsLevelReq, - query?: AdminGetInventoryItemsParams, + query?: AdminPostInventoryItemsItemLocationLevelsLevelParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/inventory-items/${inventoryItemId}/location-levels/${locationId}` @@ -146,16 +250,29 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Create stock for an Inventory Item at a Stock Location - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description creates stock levle for an Inventory Item - * @returns the Inventory Item + * Create a Location Level for a given Inventory Item. + * @param {string} inventoryItemId - The ID of the inventory item that the location level belongs to. + * @param {AdminPostInventoryItemsItemLocationLevelsReq} payload - The location level to create. + * @param {AdminPostInventoryItemsItemLocationLevelsParams} query - Configurations to apply on the returned inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} the inventory item's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.createLocationLevel(inventoryItemId, { + * location_id: "sloc_123", + * stocked_quantity: 10, + * }) + * .then(({ inventory_item }) => { + * console.log(inventory_item.id); + * }) */ createLocationLevel( inventoryItemId: string, payload: AdminPostInventoryItemsItemLocationLevelsReq, - query?: AdminGetInventoryItemsParams, + query?: AdminPostInventoryItemsItemLocationLevelsParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/inventory-items/${inventoryItemId}/location-levels` @@ -169,11 +286,21 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Removes an Inventory Item from a Stock Location. This erases trace of any quantity currently at the location. - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description deletes a location level of an Inventory Item - * @returns the Inventory Item + * Delete a location level of an Inventory Item. + * @param {string} inventoryItemId - The ID of the inventory item. + * @param {string} locationId - The ID of the location level to delete. + * @param {AdminGetInventoryItemsParams} query - Configurations to apply on the returned inventory item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} the inventory item's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.deleteLocationLevel(inventoryItemId, locationId) + * .then(({ inventory_item }) => { + * console.log(inventory_item.id); + * }) */ deleteLocationLevel( inventoryItemId: string, @@ -192,11 +319,20 @@ class AdminInventoryItemsResource extends BaseResource { } /** - * Retrieve a list of Inventory Levels related to an Inventory Item across Stock Locations - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description Retrieve a list of location levels related to an Inventory Item - * @returns the list of inventory levels related to an Inventory Item as well as the pagination properties + * Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id` passed in the `query` parameter. + * @param {string} inventoryItemId - The ID of the inventory item that the location levels belong to. + * @param {AdminGetInventoryItemsItemLocationLevelsParams} query - Filters to apply on the retrieved location levels. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} The inventory item's details and list of location levels. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.inventoryItems.listLocationLevels(inventoryItemId) + * .then(({ inventory_item }) => { + * console.log(inventory_item.location_levels); + * }) */ listLocationLevels( inventoryItemId: string, diff --git a/packages/medusa-js/src/resources/admin/invites.ts b/packages/medusa-js/src/resources/admin/invites.ts index 2144f61dce..0b6cd194e9 100644 --- a/packages/medusa-js/src/resources/admin/invites.ts +++ b/packages/medusa-js/src/resources/admin/invites.ts @@ -6,7 +6,43 @@ import { import { AdminPostInvitesPayload, ResponsePromise } from "../.." import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Invite API Routes](https://docs.medusajs.com/api/admin#invites). All its method + * are available in the JS Client under the `medusa.admin.invites` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * An admin can invite new users to manage their team. This would allow new users to authenticate as admins and perform admin functionalities. + * + * Related Guide: [How to manage invites](https://docs.medusajs.com/modules/users/admin/manage-invites). + */ class AdminInvitesResource extends BaseResource { + /** + * Accept an Invite. This will also delete the invite and create a new user that can log in and perform admin functionalities. + * The user will have the email associated with the invite, and the password provided in the `payload` parameter. + * @param {AdminPostInvitesInviteAcceptReq} payload - The user accepting the invite. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when the invite is accepted successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.invites.accept({ + * token, + * user: { + * first_name: "Brigitte", + * last_name: "Collier", + * password: "supersecret" + * } + * }) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // an error occurred + * }) + */ accept( payload: AdminPostInvitesInviteAcceptReq, customHeaders: Record = {} @@ -15,6 +51,28 @@ class AdminInvitesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create an invite. This will generate a token associated with the invite and trigger an `invite.created` event. If you have a Notification Provider installed that handles this + * event, a notification should be sent to the email associated with the invite to allow them to accept the invite. + * @param {AdminPostInvitesPayload} payload - The invite to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when the invite is created successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.invites.create({ + * user: "user@example.com", + * role: "admin" + * }) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // an error occurred + * }) + */ create( payload: AdminPostInvitesPayload, customHeaders: Record = {} @@ -23,6 +81,21 @@ class AdminInvitesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete an invite. Only invites that weren't accepted can be deleted. + * @param {string} id - The invite's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.invites.delete(inviteId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( id: string, customHeaders: Record = {} @@ -31,6 +104,20 @@ class AdminInvitesResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of invites. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of invites. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.invites.list() + * .then(({ invites }) => { + * console.log(invites.length); + * }) + */ list( customHeaders: Record = {} ): ResponsePromise { @@ -38,6 +125,26 @@ class AdminInvitesResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Resend an invite. This renews the expiry date by seven days and generates a new token for the invite. It also triggers the `invite.created` event, + * so if you have a Notification Provider installed that handles this event, a notification should be sent to the email associated with the + * invite to allow them to accept the invite. + * @param {string} id - The invite's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when the invite is resent successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.invites.resend(inviteId) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // an error occurred + * }) + */ resend(id: string, customHeaders: Record = {}): ResponsePromise { const path = `/admin/invites/${id}` return this.client.request("POST", path, undefined, {}, customHeaders) diff --git a/packages/medusa-js/src/resources/admin/notes.ts b/packages/medusa-js/src/resources/admin/notes.ts index cf9ec67c81..fdbc75772d 100644 --- a/packages/medusa-js/src/resources/admin/notes.ts +++ b/packages/medusa-js/src/resources/admin/notes.ts @@ -10,7 +10,34 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Note API Routes](https://docs.medusajs.com/api/admin#notes). All its method + * are available in the JS Client under the `medusa.admin.notes` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Notes are created by admins and can be associated with any resource. For example, an admin can add a note to an order for additional details or remarks. + */ class AdminNotesResource extends BaseResource { + /** + * Create a Note which can be associated with any resource. + * @param {AdminPostNotesReq} payload - The note to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the note's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notes.create({ + * resource_id, + * resource_type: "order", + * value: "We delivered this order" + * }) + * .then(({ note }) => { + * console.log(note.id); + * }) + */ create( payload: AdminPostNotesReq, customHeaders: Record = {} @@ -19,6 +46,24 @@ class AdminNotesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a Note's details. + * @param {string} id - The note's ID. + * @param {AdminPostNotesNoteReq} payload - The attributes to update in the note. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the note's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notes.update(noteId, { + * value: "We delivered this order" + * }) + * .then(({ note }) => { + * console.log(note.id); + * }) + */ update( id: string, payload: AdminPostNotesNoteReq, @@ -28,6 +73,21 @@ class AdminNotesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a Note. + * @param {string} id - The note's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notes.delete(noteId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( id: string, customHeaders: Record = {} @@ -36,6 +96,21 @@ class AdminNotesResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Retrieve a note's details. + * @param {string} id - The note's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the note's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notes.retrieve(noteId) + * .then(({ note }) => { + * console.log(note.id); + * }) + */ retrieve( id: string, customHeaders: Record = {} @@ -44,6 +119,40 @@ class AdminNotesResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of notes. The notes can be filtered by fields such as `resource_id` passed in the `query` parameter. The notes can also be paginated. + * @param {AdminGetNotesParams} query - Filters and pagination configurations applied on retrieved notes. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of notes with pagination fields. + * + * @example + * To list notes: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notes.list() + * .then(({ notes, limit, offset, count }) => { + * console.log(notes.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notes.list({ + * limit, + * offset + * }) + * .then(({ notes, limit, offset, count }) => { + * console.log(notes.length); + * }) + * ``` + */ list( query?: AdminGetNotesParams, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/notifications.ts b/packages/medusa-js/src/resources/admin/notifications.ts index f60b1a3450..23038c658e 100644 --- a/packages/medusa-js/src/resources/admin/notifications.ts +++ b/packages/medusa-js/src/resources/admin/notifications.ts @@ -8,7 +8,66 @@ import qs from "qs" import { ResponsePromise } from "../.." import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Notification API Routes](https://docs.medusajs.com/api/admin#notifications). All its method + * are available in the JS Client under the `medusa.admin.notifications` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Notifications are sent to customers to inform them of new updates. For example, a notification can be sent to the customer when their order is place or its state is updated. + * The notification's type, such as an email or SMS, is determined by the notification provider installed on the Medusa backend. + */ class AdminNotificationsResource extends BaseResource { + /** + * Retrieve a list of notifications. The notifications can be filtered by fields such as `event_name` or `resource_type` passed in the `query` parameter. + * The notifications can also be paginated. + * @param {AdminGetNotificationsParams} query - Filters and pagination configurations applied to the retrieved notifications. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of notifications with pagination fields. + * + * @example + * To list notifications: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notifications.list() + * .then(({ notifications }) => { + * console.log(notifications.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the notifications: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notifications.list({ + * expand: "provider" + * }) + * .then(({ notifications }) => { + * console.log(notifications.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notifications.list({ + * expand: "provider", + * limit, + * offset + * }) + * .then(({ notifications }) => { + * console.log(notifications.length); + * }) + * ``` + */ list( query?: AdminGetNotificationsParams, customHeaders: Record = {} @@ -23,6 +82,22 @@ class AdminNotificationsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Resend a previously sent notifications, with the same data but optionally to a different address. + * @param {string} id - The notification's ID. + * @param {AdminPostNotificationsNotificationResendReq} payload - The details necessary to resend the notification. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the notification's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.notifications.resend(notificationId) + * .then(({ notification }) => { + * console.log(notification.id); + * }) + */ resend( id: string, payload: AdminPostNotificationsNotificationResendReq, diff --git a/packages/medusa-js/src/resources/admin/order-edits.ts b/packages/medusa-js/src/resources/admin/order-edits.ts index 2eabdff9c9..7e9d675aab 100644 --- a/packages/medusa-js/src/resources/admin/order-edits.ts +++ b/packages/medusa-js/src/resources/admin/order-edits.ts @@ -14,7 +14,51 @@ import { ResponsePromise } from "../../typings" import BaseResource from "../base" import qs from "qs" +/** + * This class is used to send requests to [Admin Order Edit API Routes](https://docs.medusajs.com/api/admin#order-edits). All its method + * are available in the JS Client under the `medusa.admin.orderEdits` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * An admin can edit an order to remove, add, or update an item's quantity. When an admin edits an order, they're stored as an `OrderEdit`. + * + * Related Guide: [How to edit an order](https://docs.medusajs.com/modules/orders/admin/edit-order). + */ class AdminOrderEditsResource extends BaseResource { + /** + * Retrieve an order edit's details. + * @param {string} id - The ID of the order edit. + * @param {GetOrderEditsOrderEditParams} query - Configurations to apply on the retrieved order edit. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * A simple example that retrieves an order edit by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.retrieve(orderEditId) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.retrieve(orderEditId, { + * expand: "order" + * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + * ``` + */ retrieve( id: string, query?: GetOrderEditsOrderEditParams, @@ -30,6 +74,55 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of order edits. The order edits can be filtered by fields such as `q` or `order_id` passed to the `query` parameter. The order edits can also be paginated. + * @param {GetOrderEditsParams} query - Filters and pagination configurations applied to retrieved order edits. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of order edits with pagination fields. + * + * @example + * To list order edits: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.list() + * .then(({ order_edits, count, limit, offset }) => { + * console.log(order_edits.length) + * }) + * ``` + * + * To specify relations that should be retrieved within the order edits: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.list({ + * expand: "order" + * }) + * .then(({ order_edits, count, limit, offset }) => { + * console.log(order_edits.length) + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.list({ + * expand: "order", + * limit, + * offset + * }) + * .then(({ order_edits, count, limit, offset }) => { + * console.log(order_edits.length) + * }) + * ``` + */ list( query?: GetOrderEditsParams, customHeaders: Record = {} @@ -44,6 +137,21 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Create an order edit. + * @param {AdminPostOrderEditsReq} payload - The order edit to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.create({ orderId }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ create( payload: AdminPostOrderEditsReq, customHeaders: Record = {} @@ -52,6 +160,24 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update an Order Edit's details. + * @param {string} id - The ID of the order edit. + * @param {AdminPostOrderEditsOrderEditReq} payload - The attributes to update in an order edit. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.update(orderEditId, { + * internal_note: "internal reason XY" + * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ update( id: string, payload: AdminPostOrderEditsOrderEditReq, @@ -61,6 +187,21 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete an order edit. Only order edits that have the status `created` can be deleted. + * @param {string} id - The ID of the order edit. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.delete(orderEditId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) + */ delete( id: string, customHeaders: Record = {} @@ -69,6 +210,26 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Create a line item change in the order edit that indicates adding an item in the original order. The item will not be added to the original order until the order edit is + * confirmed. + * @param {string} id - The ID of the order edit to add the line item change to. + * @param {AdminPostOrderEditsEditLineItemsReq} payload - The line item change to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.addLineItem(orderEditId, { + * variant_id, + * quantity + * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ addLineItem( id: string, payload: AdminPostOrderEditsEditLineItemsReq, @@ -78,6 +239,22 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a line item change that indicates the addition, deletion, or update of a line item in the original order. + * @param {string} orderEditId - The ID of the order edit. + * @param {string} itemChangeId - The ID of the line item change. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.deleteItemChange(orderEdit_id, itemChangeId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) + */ deleteItemChange( orderEditId: string, itemChangeId: string, @@ -87,6 +264,22 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Request customer confirmation of an order edit. This would emit the event `order-edit.requested` which Notification Providers listen to and send + * a notification to the customer about the order edit. + * @param {string} id - The ID of the order edit. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.requestConfirmation(orderEditId) + * .then({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ requestConfirmation( id: string, customHeaders: Record = {} @@ -95,6 +288,21 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Cancel an order edit. + * @param {string} id - The ID of the order edit to cancel. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.cancel(orderEditId) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ cancel( id: string, customHeaders: Record = {} @@ -103,6 +311,21 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Confirm an order edit. This will reflect the changes in the order edit on the associated order. + * @param {string} id - The ID of the order edit to confirm. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.confirm(orderEditId) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ confirm( id: string, customHeaders: Record = {} @@ -111,6 +334,26 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Create or update a line item change in the order edit that indicates addition, deletion, or update of a line item into an original order. Line item changes + * are only reflected on the original order after the order edit is confirmed. + * @param {string} orderEditId - The ID of the order edit that the line item belongs to. + * @param {string} itemId - The ID of the line item to create or update its line item change. + * @param {AdminPostOrderEditsEditLineItemsLineItemReq} payload - The creation or update of the line item change. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.updateLineItem(orderEditId, lineItemId, { + * quantity: 5 + * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ updateLineItem( orderEditId: string, itemId: string, @@ -121,6 +364,23 @@ class AdminOrderEditsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a line item change in the order edit that indicates deleting an item in the original order. The item in the original order will not be deleted until the order edit is + * confirmed. + * @param {string} orderEditId - The ID of the order edit that the line item change belongs to. + * @param {string} itemId - The ID of the line item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orderEdits.removeLineItem(orderEditId, lineItemId) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ removeLineItem( orderEditId: string, itemId: string, diff --git a/packages/medusa-js/src/resources/admin/orders.ts b/packages/medusa-js/src/resources/admin/orders.ts index 633b5ed08f..39fdb4f3bc 100644 --- a/packages/medusa-js/src/resources/admin/orders.ts +++ b/packages/medusa-js/src/resources/admin/orders.ts @@ -21,7 +21,36 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Order API Routes](https://docs.medusajs.com/api/admin#orders). All its method + * are available in the JS Client under the `medusa.admin.orders` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Orders are purchases made by customers, typically through a storefront using {@link CartsResource}. Draft orders created by the admin are also transformed to an Order once the payment is captured. + * Managing orders include managing fulfillment, payment, claims, reservations, and more. + * + * Related Guide: [How to manage orders](https://docs.medusajs.com/modules/orders/admin/manage-orders). + */ class AdminOrdersResource extends BaseResource { + /** + * Update and order's details. + * @param {string} id - The order's ID. + * @param {AdminPostOrdersOrderReq} payload - The attributes to update in the order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.update(orderId, { + * email: "user@example.com" + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ update( id: string, payload: AdminPostOrdersOrderReq, @@ -31,6 +60,40 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Retrieve an order's details. + * @param {string} id - The order's ID. + * @param {FindParams} query - Configurations to apply on the retrieved order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * A simple example that retrieves an order by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.retrieve(orderId) + * .then(({ order }) => { + * console.log(order.id); + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.retrieve(orderId, { + * expand: "customer" + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + * ``` + */ retrieve( id: string, query?: FindParams, @@ -46,6 +109,55 @@ class AdminOrdersResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of orders. The orders can be filtered by fields such as `status` or `display_id` passed in the `query` parameter. The order can also be paginated. + * @param {AdminGetOrdersParams} query - Filters and pagination configurations applied on the retrieved orders. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of orders with pagination fields. + * + * @example + * To list orders: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.list() + * .then(({ orders, limit, offset, count }) => { + * console.log(orders.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the orders: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.list({ + * expand: "customers" + * }) + * .then(({ orders, limit, offset, count }) => { + * console.log(orders.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.list({ + * expand: "customers", + * limit, + * offset + * }) + * .then(({ orders, limit, offset, count }) => { + * console.log(orders.length); + * }) + * ``` + */ list( query?: AdminGetOrdersParams, customHeaders: Record = {} @@ -60,6 +172,21 @@ class AdminOrdersResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Complete an order and change its status. A canceled order can't be completed. + * @param {string} id - The order's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.complete(orderId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ complete( id: string, customHeaders: Record = {} @@ -68,6 +195,21 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Capture all the payments associated with an order. The payment of canceled orders can't be captured. + * @param {string} id - The ID of the order whose payments should be captured. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.capturePayment(orderId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ capturePayment( id: string, customHeaders: Record = {} @@ -76,6 +218,25 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Refund an amount for an order. The amount must be less than or equal the `refundable_amount` of the order. + * @param {string} id - The ID of the order whose customer should be refunded. + * @param {AdminPostOrdersOrderRefundsReq} payload - The refund's details. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.refundPayment(orderId, { + * amount: 1000, + * reason: "Do not like it" + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ refundPayment( id: string, payload: AdminPostOrdersOrderRefundsReq, @@ -85,6 +246,30 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a Fulfillment of an Order using the fulfillment provider, and change the order's fulfillment status to either `partially_fulfilled` or `fulfilled`, depending on + * whether all the items were fulfilled. + * @param {string} id - The ID of the order that the fulfillment belongs to. + * @param {AdminPostOrdersOrderFulfillmentsReq} payload - The fulfillment to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.createFulfillment(orderId, { + * items: [ + * { + * item_id, + * quantity: 1 + * } + * ] + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ createFulfillment( id: string, payload: AdminPostOrdersOrderFulfillmentsReq, @@ -94,6 +279,22 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Cancel an order's fulfillment and change its fulfillment status to `canceled`. + * @param {string} id - The ID of the order that the fulfillment belongs to. + * @param {string} fulfillmentId - The fulfillment's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.cancelFulfillment(orderId, fulfillmentId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ cancelFulfillment( id: string, fulfillmentId: string, @@ -103,6 +304,23 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Cancel a swap's fulfillment and change its fulfillment status to `canceled`. + * @param {string} id - The ID of the order that the swap is associated with. + * @param {string} swapId - The ID of the swap the fulfillment belongs to. + * @param {string} fulfillmentId - The fulfillment's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.cancelSwapFulfillment(orderId, swapId, fulfillmentId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ cancelSwapFulfillment( id: string, swapId: string, @@ -113,6 +331,23 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Cancel a claim's fulfillment and change its fulfillment status to `canceled`. + * @param {string} id - The ID of the order that the claim is associated with. + * @param {string} claimId - The claim's ID. + * @param {string} fulfillmentId - The fulfillment's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.cancelClaimFulfillment(orderId, claimId, fulfillmentId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ cancelClaimFulfillment( id: string, claimId: string, @@ -123,6 +358,25 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Create a shipment and mark a fulfillment as shipped. This changes the order's fulfillment status to either `partially_shipped` or `shipped`, depending on + * whether all the items were shipped. + * @param {string} id - The ID of the order + * @param {AdminPostOrdersOrderShipmentReq} payload - The shipment to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.createShipment(order_id, { + * fulfillment_id + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ createShipment( id: string, payload: AdminPostOrdersOrderShipmentReq, @@ -132,6 +386,29 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Request and create a return for items in an order. If the return shipping method is specified, it will be automatically fulfilled. + * @param {string} id - The order's ID. + * @param {AdminPostOrdersOrderReturnsReq} payload - The return to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the return under the `returns` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.requestReturn(orderId, { + * items: [ + * { + * item_id, + * quantity: 1 + * } + * ] + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ requestReturn( id: string, payload: AdminPostOrdersOrderReturnsReq, @@ -141,6 +418,22 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Cancel an order and change its status. This will also cancel any associated fulfillments and payments, and it may fail if the payment or fulfillment Provider + * is unable to cancel the payment/fulfillment. + * @param {string} id - The order's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.cancel(orderId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ cancel( id: string, customHeaders: Record = {} @@ -149,6 +442,25 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Add a shipping method to an order. If another shipping method exists with the same shipping profile, the previous shipping method will be replaced. + * @param {string} id - The order's ID. + * @param {AdminPostOrdersOrderShippingMethodsReq} payload - The shipping method to be added. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.addShippingMethod(orderId, { + * price: 1000, + * option_id + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ addShippingMethod( id: string, payload: AdminPostOrdersOrderShippingMethodsReq, @@ -158,6 +470,21 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Archive an order and change its status. + * @param {string} id - The order's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.archive(orderId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ archive( id: string, customHeaders: Record = {} @@ -166,6 +493,29 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Create a swap for an order. This includes creating a return that is associated with the swap. + * @param {string} id - The order's ID. + * @param {AdminPostOrdersOrderSwapsReq} payload - The swap to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `swaps` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.createSwap(orderId, { + * return_items: [ + * { + * item_id, + * quantity: 1 + * } + * ] + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ createSwap( id: string, payload: AdminPostOrdersOrderSwapsReq, @@ -175,6 +525,22 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Cancel a swap and change its status. + * @param {string} id - The ID of the order that the swap belongs to. + * @param {string} swapId - The swap's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `swaps` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.cancelSwap(orderId, swapId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ cancelSwap( id: string, swapId: string, @@ -184,6 +550,26 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Create a Fulfillment for a Swap and change its fulfillment status to `fulfilled`. If it requires any additional actions, + * its fulfillment status may change to `requires_action`. + * @param {string} id - The ID of the order that the swap belongs to. + * @param {string} swapId - The swap's ID. + * @param {AdminPostOrdersOrderSwapsSwapFulfillmentsReq} payload - The fulfillment to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `swaps` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.fulfillSwap(orderId, swapId, { + * no_notification: true, + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ fulfillSwap( id: string, swapId: string, @@ -194,6 +580,26 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a shipment for a swap and mark its fulfillment as shipped. This changes the swap's fulfillment status to either `shipped` or `partially_shipped`, depending on + * whether all the items were shipped. + * @param {string} id - The ID of the order that the swap belongs to. + * @param {string} swapId - The swap's ID. + * @param {AdminPostOrdersOrderSwapsSwapShipmentsReq} payload - The shipment to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `swaps` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.createSwapShipment(orderId, swapId, { + * fulfillment_id + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ createSwapShipment( id: string, swapId: string, @@ -204,6 +610,23 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Process a swap's payment either by refunding or issuing a payment. This depends on the `difference_due` of the swap. If `difference_due` is negative, the amount is refunded. + * If `difference_due` is positive, the amount is captured. + * @param {string} id - The ID of the order that the swap belongs to. + * @param {string} swapId - The swap's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `swaps` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.processSwapPayment(orderId, swapId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ processSwapPayment( id: string, swapId: string, @@ -213,6 +636,31 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Create a claim for an order. If a return shipping method is specified, a return will also be created and associated with the claim. If the claim's type is `refund`, + * the refund is processed as well. + * @param {string} id - The order's ID. + * @param {AdminPostOrdersOrderClaimsReq} payload - The claim to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `claims` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.createClaim(orderId, { + * type: 'refund', + * claim_items: [ + * { + * item_id, + * quantity: 1 + * } + * ] + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ createClaim( id: string, payload: AdminPostOrdersOrderClaimsReq, @@ -222,6 +670,22 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Cancel a claim and change its status. A claim can't be canceled if it has a refund, if its fulfillments haven't been canceled, of if its associated return hasn't been canceled. + * @param {string} id - The ID of the order that the claim belongs to. + * @param {string} claimId - The claim's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `claims` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.cancelClaim(orderId, claimId) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ cancelClaim( id: string, claimId: string, @@ -231,6 +695,25 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Update a claim's details. + * @param {string} id - The ID of the order that the claim belongs to. + * @param {string} claimId - The claim's ID. + * @param {AdminPostOrdersOrderClaimsClaimReq} payload - The attributes to update in the claim. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `claims` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.updateClaim(orderId, claimId, { + * no_notification: true + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ updateClaim( id: string, claimId: string, @@ -241,6 +724,25 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a Fulfillment for a Claim, and change its fulfillment status to `partially_fulfilled` or `fulfilled` depending on whether all the items were fulfilled. + * It may also change the status to `requires_action` if any actions are required. + * @param {string} id - The ID of the order that the claim belongs to. + * @param {string} claimId - The claim's ID. + * @param {AdminPostOrdersOrderClaimsClaimFulfillmentsReq} payload - The fulfillment to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `claims` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.fulfillClaim(orderId, claimId, { + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ fulfillClaim( id: string, claimId: string, @@ -251,6 +753,26 @@ class AdminOrdersResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a shipment for the claim and mark its fulfillment as shipped. If the shipment is created successfully, this changes the claim's fulfillment status + * to either `partially_shipped` or `shipped`, depending on whether all the items were shipped. + * @param {string} id - The ID of the order that the claim belongs to. + * @param {string} claimId - The claim's ID. + * @param {AdminPostOrdersOrderClaimsClaimShipmentsReq} payload - The shipment to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order's details. You can access the swap under the `claims` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.orders.createClaimShipment(orderId, claimId, { + * fulfillment_id + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) + */ createClaimShipment( id: string, claimId: string, diff --git a/packages/medusa-js/src/resources/admin/payment-collections.ts b/packages/medusa-js/src/resources/admin/payment-collections.ts index ed381dca2f..68a4060262 100644 --- a/packages/medusa-js/src/resources/admin/payment-collections.ts +++ b/packages/medusa-js/src/resources/admin/payment-collections.ts @@ -8,7 +8,49 @@ import { ResponsePromise } from "../../typings" import BaseResource from "../base" import qs from "qs" +/** + * This class is used to send requests to [Admin Payment Collection API Routes](https://docs.medusajs.com/api/admin#payment-collections). All its method + * are available in the JS Client under the `medusa.admin.paymentCollections` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments. + */ class AdminPaymentCollectionsResource extends BaseResource { + /** + * Retrieve a Payment Collection's details. + * @param {string} id - The ID of the payment collection. + * @param {AdminGetPaymentCollectionsParams} query - Configurations to apply on the retrieved payment collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * A simple example that retrieves a payment collection by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.retrieve(paymentCollectionId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.retrieve(paymentCollectionId, { + * expand: "currency" + * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * ``` + */ retrieve( id: string, query?: AdminGetPaymentCollectionsParams, @@ -24,6 +66,24 @@ class AdminPaymentCollectionsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Update a payment collection's details. + * @param {string} id - The ID of the payment collection. + * @param {AdminUpdatePaymentCollectionsReq} payload - The attributes to update in the payment collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.update(paymentCollectionId, { + * description + * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + */ update( id: string, payload: AdminUpdatePaymentCollectionsReq, @@ -33,6 +93,21 @@ class AdminPaymentCollectionsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a payment collection. Only payment collections with the statuses `canceled` or `not_paid` can be deleted. + * @param {string} id - The ID of the payment collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.delete(paymentCollectionId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) + */ delete( id: string, customHeaders: Record = {} @@ -41,6 +116,21 @@ class AdminPaymentCollectionsResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Set the status of a payment collection as `authorized`. This will also change the `authorized_amount` of the payment collection. + * @param {string} id - The ID of the payment collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.paymentCollections.markAsAuthorized(paymentCollectionId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + */ markAsAuthorized( id: string, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/payments.ts b/packages/medusa-js/src/resources/admin/payments.ts index b93766c775..0316e88cac 100644 --- a/packages/medusa-js/src/resources/admin/payments.ts +++ b/packages/medusa-js/src/resources/admin/payments.ts @@ -8,7 +8,31 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Payment API Routes](https://docs.medusajs.com/api/admin#payments). All its method + * are available in the JS Client under the `medusa.admin.payments` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A payment can be related to an order, swap, return, or more. It can be captured or refunded. + */ class AdminPaymentsResource extends BaseResource { + /** + * Retrieve a payment's details. + * @param {string} id - The payment's ID. + * @param {GetPaymentsParams} query - Configurations to apply on the retrieved payment. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.payments.retrieve(paymentId) + * .then(({ payment }) => { + * console.log(payment.id); + * }) + */ retrieve( id: string, query?: GetPaymentsParams, @@ -24,6 +48,21 @@ class AdminPaymentsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Capture a payment. + * @param {string} id - The payment's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.payments.capturePayment(paymentId) + * .then(({ payment }) => { + * console.log(payment.id); + * }) + */ capturePayment( id: string, customHeaders: Record = {} @@ -32,6 +71,26 @@ class AdminPaymentsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Refund a payment. The payment must be captured first. + * @param {string} id - The payment's ID. + * @param {AdminPostPaymentRefundsReq} payload - The refund to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the refund's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.payments.refundPayment(paymentId, { + * amount: 1000, + * reason: "return", + * note: "Do not like it", + * }) + * .then(({ payment }) => { + * console.log(payment.id); + * }) + */ refundPayment( id: string, payload: AdminPostPaymentRefundsReq, diff --git a/packages/medusa-js/src/resources/admin/price-lists.ts b/packages/medusa-js/src/resources/admin/price-lists.ts index c98a164e9e..4ed135b449 100644 --- a/packages/medusa-js/src/resources/admin/price-lists.ts +++ b/packages/medusa-js/src/resources/admin/price-lists.ts @@ -7,15 +7,51 @@ import { AdminPostPriceListsPriceListPriceListReq, AdminPostPriceListsPriceListReq, AdminPriceListDeleteBatchRes, + AdminPriceListDeleteProductPricesRes, AdminPriceListDeleteRes, + AdminPriceListDeleteVariantPricesRes, AdminPriceListRes, AdminPriceListsListRes, + AdminPriceListsProductsListRes, } from "@medusajs/medusa" import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Price List API Routes](https://docs.medusajs.com/api/admin#price-lists). All its method + * are available in the JS Client under the `medusa.admin.priceLists` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A price list are special prices applied to products based on a set of conditions, such as customer group. + * + * Related Guide: [How to manage price lists](https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists). + */ class AdminPriceListResource extends BaseResource { + /** + * Create a price list. + * @param {AdminPostPriceListsPriceListReq} payload - The price list to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the price list details. + * + * @example + * medusa.admin.priceLists.create({ + * name: "New Price List", + * description: "A new price list", + * type: PriceListType.SALE, + * prices: [ + * { + * amount: 1000, + * variant_id, + * currency_code: "eur" + * } + * ] + * }) + * .then(({ price_list }) => { + * console.log(price_list.id); + * }) + */ create( payload: AdminPostPriceListsPriceListReq, customHeaders: Record = {} @@ -24,6 +60,24 @@ class AdminPriceListResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a price list's details. + * @param {string} id - The ID of the price list. + * @param {AdminPostPriceListsPriceListPriceListReq} payload - The attributes to update in the price list. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the price list details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.update(priceListId, { + * name: "New Price List" + * }) + * .then(({ price_list }) => { + * console.log(price_list.id); + * }) + */ update( id: string, payload: AdminPostPriceListsPriceListPriceListReq, @@ -33,6 +87,21 @@ class AdminPriceListResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a price list and its associated prices. + * @param {string} id - The ID of the price list. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.delete(priceListId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( id: string, customHeaders: Record = {} @@ -41,6 +110,21 @@ class AdminPriceListResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Retrieve a price list's details. + * @param {string} id - The ID of the price list. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the price list details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.retrieve(priceListId) + * .then(({ price_list }) => { + * console.log(price_list.id); + * }) + */ retrieve( id: string, customHeaders: Record = {} @@ -49,6 +133,55 @@ class AdminPriceListResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of price lists. The price lists can be filtered by fields such as `q` or `status` passed in the `query` parameter. The price lists can also be sorted or paginated. + * @param {AdminGetPriceListPaginationParams} query - Filters and pagination configurations to apply on the retrieved price lists. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of price lists with pagination fields. + * + * @example + * To list price lists: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.list() + * .then(({ price_lists, limit, offset, count }) => { + * console.log(price_lists.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the price lists: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.list({ + * expand: "prices" + * }) + * .then(({ price_lists, limit, offset, count }) => { + * console.log(price_lists.length); + * }) + * ``` + * + * By default, only the first `10` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.list({ + * expand: "prices", + * limit, + * offset + * }) + * .then(({ price_lists, limit, offset, count }) => { + * console.log(price_lists.length); + * }) + * ``` + */ list( query?: AdminGetPriceListPaginationParams, customHeaders: Record = {} @@ -63,11 +196,61 @@ class AdminPriceListResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a price list's products. The products can be filtered by fields such as `q` or `status` passed in the `query` parameter. The products can also be sorted or paginated. + * @param {string} id - The ID of the price list. + * @param {AdminGetPriceListsPriceListProductsParams} query - Filters and pagination configurations applied on the retrieved products. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of products with pagination fields. + * + * @example + * To list products in a price list: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.listProducts(priceListId) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the products: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.listProducts(priceListId, { + * expand: "variants" + * }) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.listProducts(priceListId, { + * expand: "variants", + * limit, + * offset + * }) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + */ listProducts( id: string, query?: AdminGetPriceListsPriceListProductsParams, customHeaders: Record = {} - ): ResponsePromise { + ): ResponsePromise { let path = `/admin/price-lists/${id}/products` if (query) { @@ -78,6 +261,30 @@ class AdminPriceListResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Add or update a list of prices in a price list. + * @param {string} id - The ID of the price list. + * @param {AdminPostPriceListPricesPricesReq} payload - The details of prices to add or update. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the price list's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.addPrices(priceListId, { + * prices: [ + * { + * amount: 1000, + * variant_id, + * currency_code: "eur" + * } + * ] + * }) + * .then(({ price_list }) => { + * console.log(price_list.id); + * }) + */ addPrices( id: string, payload: AdminPostPriceListPricesPricesReq, @@ -87,6 +294,26 @@ class AdminPriceListResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a list of prices in a price list + * @param {string} id - The ID of the price list. + * @param {AdminDeletePriceListPricesPricesReq} payload - The prices to delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.deletePrices(priceListId, { + * price_ids: [ + * price_id + * ] + * }) + * .then(({ ids, object, deleted }) => { + * console.log(ids.length); + * }) + */ deletePrices( id: string, payload: AdminDeletePriceListPricesPricesReq, @@ -96,29 +323,82 @@ class AdminPriceListResource extends BaseResource { return this.client.request("DELETE", path, payload, {}, customHeaders) } + /** + * Delete all the prices related to a specific product in a price list. + * @param {string} priceListId - The ID of the price list. + * @param {string} productId - The product's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.deleteProductPrices(priceListId, productId) + * .then(({ ids, object, deleted }) => { + * console.log(ids.length); + * }) + */ deleteProductPrices( priceListId: string, productId: string, customHeaders: Record = {} - ): ResponsePromise { + ): ResponsePromise { const path = `/admin/price-lists/${priceListId}/products/${productId}/prices` return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Delete all the prices related to a specific product variant in a price list. + * @param {string} priceListId - The ID of the price list. + * @param {string} variantId - The ID of the product variant. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.deleteVariantPrices(priceListId, variantId) + * .then(({ ids, object, deleted }) => { + * console.log(ids); + * }) + */ deleteVariantPrices( priceListId: string, variantId: string, customHeaders: Record = {} - ): ResponsePromise { + ): ResponsePromise { const path = `/admin/price-lists/${priceListId}/variants/${variantId}/prices` return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Delete all the prices associated with multiple products in a price list. + * @param {string} priceListId - The ID of the price list. + * @param {AdminDeletePriceListsPriceListProductsPricesBatchReq} payload - The products whose prices should be deleted. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.priceLists.deleteProductsPrices(priceListId, { + * product_ids: [ + * productId1, + * productId2, + * ] + * }) + * .then(({ ids, object, deleted }) => { + * console.log(ids.length); + * }) + */ deleteProductsPrices( priceListId: string, payload: AdminDeletePriceListsPriceListProductsPricesBatchReq, customHeaders: Record = {} - ): ResponsePromise { + ): ResponsePromise { const path = `/admin/price-lists/${priceListId}/products/prices/batch` return this.client.request("DELETE", path, payload, {}, customHeaders) } diff --git a/packages/medusa-js/src/resources/admin/product-categories.ts b/packages/medusa-js/src/resources/admin/product-categories.ts index 1a6784c208..daad77449d 100644 --- a/packages/medusa-js/src/resources/admin/product-categories.ts +++ b/packages/medusa-js/src/resources/admin/product-categories.ts @@ -3,7 +3,6 @@ import { AdminGetProductCategoriesParams, AdminPostProductCategoriesCategoryProductsBatchReq, AdminPostProductCategoriesReq, - AdminPostProductCategoriesCategoryParams, AdminProductCategoriesCategoryDeleteRes, AdminProductCategoriesListRes, AdminProductCategoriesCategoryRes, @@ -15,12 +14,52 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Product Category API Routes](https://docs.medusajs.com/api/admin#product-categories). All its method + * are available in the JS Client under the `medusa.admin.productCategories` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Products can be categoriezed into categories. A product can be added into more than one category. + * + * Related Guide: [How to manage product categories](https://docs.medusajs.com/modules/products/admin/manage-categories). + * + * @featureFlag product_categories + */ class AdminProductCategoriesResource extends BaseResource { - /** retrieve a product category - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `product_categories` in your medusa backend project. - * @description gets a product category - * @returns a medusa product category + /** + * Retrieve a product category's details. + * @param {string} productCategoryId - The ID of the product category. + * @param {AdminGetProductCategoryParams} query - Configurations to apply on the retrieved product category. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product category's details. + * + * @example + * A simple example that retrieves an order by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.retrieve(productCategoryId) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.retrieve(productCategoryId, { + * expand: "category_children" + * }) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) + * ``` */ retrieve( productCategoryId: string, @@ -37,9 +76,22 @@ class AdminProductCategoriesResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } - /* * - * Create a medusa product category - * @returns the created product category + /** + * Create a product category. + * @param {AdminPostProductCategoriesReq} payload - The product category's details. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product category's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.create({ + * name: "Skinny Jeans", + * }) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) */ create( payload: AdminPostProductCategoriesReq, @@ -49,11 +101,23 @@ class AdminProductCategoriesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } - /** update a product category - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `product_categories` in your medusa backend project. - * @description updates a product category - * @returns the updated medusa product category + /** + * Updates a product category. + * @param {string} productCategoryId - The ID of the product category. + * @param {AdminPostProductCategoriesCategoryReq} payload - The attributes to update in the product category. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product category's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.update(productCategoryId, { + * name: "Skinny Jeans" + * }) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) */ update( productCategoryId: string, @@ -65,11 +129,54 @@ class AdminProductCategoriesResource extends BaseResource { } /** - * Retrieve a list of product categories - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `product_categories` in your medusa backend project. - * @description Retrieve a list of product categories - * @returns the list of product category as well as the pagination properties + * Retrieve a list of product categories. The product categories can be filtered by fields such as `q` or `handle` passed in the `query` parameter. + * The product categories can also be paginated. + * @param {AdminGetProductCategoriesParams} query - Filters and pagination configurations to apply on the retrieved product categories. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product categories with pagination fields. + * + * @example + * To list product categories: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.list() + * .then(({ product_categories, limit, offset, count }) => { + * console.log(product_categories.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the product category: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.list({ + * expand: "category_children" + * }) + * .then(({ product_categories, limit, offset, count }) => { + * console.log(product_categories.length); + * }) + * ``` + * + * By default, only the first `100` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.list({ + * expand: "category_children", + * limit, + * offset + * }) + * .then(({ product_categories, limit, offset, count }) => { + * console.log(product_categories.length); + * }) + * ``` */ list( query?: AdminGetProductCategoriesParams, @@ -86,11 +193,19 @@ class AdminProductCategoriesResource extends BaseResource { } /** - * Delete a product category - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `product_categories` in your medusa backend project. - * @description gets a product category - * @returns an deletion result + * Delete a product category. This does not delete associated products. + * @param {string} productCategoryId - The ID of the product category. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.delete(productCategoryId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( productCategoryId: string, @@ -101,11 +216,26 @@ class AdminProductCategoriesResource extends BaseResource { } /** - * Remove products from a product category - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `product_categories` in your medusa backend project. - * @description Remove products from a product category - * @returns a medusa product category + * Remove a list of products from a product category. + * @param {string} productCategoryId - The ID of the product category. + * @param {AdminDeleteProductCategoriesCategoryProductsBatchReq} payload - The products to delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product category's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.removeProducts(productCategoryId, { + * product_ids: [ + * { + * id: productId + * } + * ] + * }) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) */ removeProducts( productCategoryId: string, @@ -117,11 +247,26 @@ class AdminProductCategoriesResource extends BaseResource { } /** - * Add products to a product category - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `product_categories` in your medusa backend project. - * @description Add products to a product category - * @returns a medusa product category + * Add a list of products to a product category. + * @param {string} productCategoryId - The ID of the product category. + * @param {AdminPostProductCategoriesCategoryProductsBatchReq} payload - The products to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product category's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productCategories.addProducts(productCategoryId, { + * product_ids: [ + * { + * id: productId + * } + * ] + * }) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) */ addProducts( productCategoryId: string, diff --git a/packages/medusa-js/src/resources/admin/product-tags.ts b/packages/medusa-js/src/resources/admin/product-tags.ts index 529490f8b3..c4ef68b047 100644 --- a/packages/medusa-js/src/resources/admin/product-tags.ts +++ b/packages/medusa-js/src/resources/admin/product-tags.ts @@ -6,7 +6,49 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Product Tag API Routes](https://docs.medusajs.com/api/admin#product-tags). All its method + * are available in the JS Client under the `medusa.admin.productTags` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Product tags are string values created when you create or update a product with a new tag. + * Products can have more than one tag, and products can share tags. This allows admins to associate products to similar tags that can be used to filter products. + */ class AdminProductTagsResource extends BaseResource { + /** + * Retrieve a list of product tags. The product tags can be filtered by fields such as `q` or `value` passed in the `query` parameter. The product tags can also be sorted or paginated. + * @param {AdminGetProductTagsParams} query - Filters and pagination configurations to apply on the retrieved product tags. + * @returns {ResponsePromise} Resolves to the list of product tags with pagination fields. + * + * @example + * To list product tags: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productTags.list() + * .then(({ product_tags }) => { + * console.log(product_tags.length); + * }) + * ``` + * + * By default, only the first `10` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productTags.list({ + * limit, + * offset + * }) + * .then(({ product_tags }) => { + * console.log(product_tags.length); + * }) + * ``` + */ list( query?: AdminGetProductTagsParams ): ResponsePromise { diff --git a/packages/medusa-js/src/resources/admin/product-types.ts b/packages/medusa-js/src/resources/admin/product-types.ts index 1fba4052c6..78463b47be 100644 --- a/packages/medusa-js/src/resources/admin/product-types.ts +++ b/packages/medusa-js/src/resources/admin/product-types.ts @@ -6,7 +6,51 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Product Type API Routes](https://docs.medusajs.com/api/admin#product-types). All its method + * are available in the JS Client under the `medusa.admin.productTypes` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Product types are string values created when you create or update a product with a new type. + * Products can have one type, and products can share types. This allows admins to associate products with a type that can be used to filter products. + */ class AdminProductTypesResource extends BaseResource { + /** + * Retrieve a list of product types. The product types can be filtered by fields such as `q` or `value` passed in the `query` parameter. + * The product types can also be sorted or paginated. + * @param {AdminGetProductTypesParams} query - Filters and pagination configurations to apply on the retrieved product types. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product types with pagination fields. + * + * @example + * To list product types: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productTypes.list() + * .then(({ product_types }) => { + * console.log(product_types.length); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.productTypes.list({ + * limit, + * offset + * }) + * .then(({ product_types }) => { + * console.log(product_types.length); + * }) + * ``` + */ list( query?: AdminGetProductTypesParams, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/products.ts b/packages/medusa-js/src/resources/admin/products.ts index 12dfc350f7..9f312018c7 100644 --- a/packages/medusa-js/src/resources/admin/products.ts +++ b/packages/medusa-js/src/resources/admin/products.ts @@ -19,7 +19,36 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Product API Routes](https://docs.medusajs.com/api/admin#products). All its method + * are available in the JS Client under the `medusa.admin.products` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Products are saleable items in a store. This also includes [saleable gift cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product) in a store. + * + * Related Guide: [How to manage products](https://docs.medusajs.com/modules/products/admin/manage-products). + */ class AdminProductsResource extends BaseResource { + /** + * Create a new Product. This API Route can also be used to create a gift card if the `is_giftcard` field is set to `true`. + * @param {AdminPostProductsReq} payload - The product to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.create({ + * title: "Shirt", + * is_giftcard: false, + * discountable: true + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ create( payload: AdminPostProductsReq, customHeaders: Record = {} @@ -28,6 +57,21 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Retrieve a product's details. + * @param {string} id - The product's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.retrieve(productId) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ retrieve( id: string, customHeaders: Record = {} @@ -36,6 +80,24 @@ class AdminProductsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Update a Product's details. + * @param {string} id - The product's ID. + * @param {AdminPostProductsProductReq} payload - The attributes to update in a product. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.update(productId, { + * title: "Shirt", + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ update( id: string, payload: AdminPostProductsProductReq, @@ -45,6 +107,21 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a product and its associated product variants and options. + * @param {string} id - The product's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.delete(productId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( id: string, customHeaders: Record = {} @@ -53,6 +130,55 @@ class AdminProductsResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of products. The products can be filtered by fields such as `q` or `status` passed in the `query` parameter. The products can also be sorted or paginated. + * @param {AdminGetProductsParams} query - Filters and pagination configurations to apply on the retrieved products. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of products with pagination fields. + * + * @example + * To list products: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.list() + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the products: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.list({ + * expand: "images" + * }) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.list({ + * expand: "images", + * limit, + * offset + * }) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + */ list( query?: AdminGetProductsParams, customHeaders: Record = {} @@ -68,6 +194,8 @@ class AdminProductsResource extends BaseResource { } /** + * @ignore + * * @deprecated Use {@link AdminProductTypesResource.list} instead. */ listTypes( @@ -77,6 +205,20 @@ class AdminProductsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of Product Tags with how many times each is used in products. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of tags. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.listTags() + * .then(({ tags }) => { + * console.log(tags.length); + * }) + */ listTags( customHeaders: Record = {} ): ResponsePromise { @@ -84,6 +226,26 @@ class AdminProductsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Set the metadata of a product. It can be any key-value pair, which allows adding custom data to a product. Learn about how you can update and delete the metadata attribute + * [here](https://docs.medusajs.com/development/entities/overview#metadata-attribute). + * @param {string} id - The product's ID. + * @param {AdminPostProductsProductMetadataReq} payload - The metadata details to add, update, or delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.setMetadata(productId, { + * key: "test", + * value: "true" + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ setMetadata( id: string, payload: AdminPostProductsProductMetadataReq, @@ -93,6 +255,37 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a product variant associated with a product. Each product variant must have a unique combination of product option values. + * @param {string} id - The ID of the product that the variant belongs to. + * @param {AdminPostProductsProductVariantsReq} payload - The product variant to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. You can access the variant under the `variants` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.createVariant(productId, { + * title: "Color", + * prices: [ + * { + * amount: 1000, + * currency_code: "eur" + * } + * ], + * options: [ + * { + * option_id, + * value: "S" + * } + * ], + * inventory_quantity: 100 + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ createVariant( id: string, payload: AdminPostProductsProductVariantsReq, @@ -102,6 +295,38 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a product variant's details. + * @param {string} id - The ID of the product that the variant belongs to. + * @param {string} variantId - The ID of the product variant. + * @param {AdminPostProductsProductVariantsVariantReq} payload - The attributes to update in the product variant. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. You can access the variant under the `variants` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.updateVariant(productId, variantId, { + * title: "Color", + * prices: [ + * { + * amount: 1000, + * currency_code: "eur" + * } + * ], + * options: [ + * { + * option_id, + * value: "S" + * } + * ], + * inventory_quantity: 100 + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ updateVariant( id: string, variantId: string, @@ -112,6 +337,22 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a product variant. + * @param {string} id - The ID of the product that the variant belongs to. + * @param {string} variantId - The ID of the product variant. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.deleteVariant(productId, variantId) + * .then(({ variant_id, object, deleted, product }) => { + * console.log(product.id); + * }) + */ deleteVariant( id: string, variantId: string, @@ -121,6 +362,24 @@ class AdminProductsResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Add a product option to a product. + * @param {string} id - The product's ID. + * @param {AdminPostProductsProductOptionsReq} payload - The option to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. You can access the variant under the `options` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.addOption(productId, { + * title: "Size" + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ addOption( id: string, payload: AdminPostProductsProductOptionsReq, @@ -130,6 +389,25 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a product option's details. + * @param {string} id - The ID of the product that the option belongs to. + * @param {string} optionId - The ID of the product option. + * @param {AdminPostProductsProductOptionsOption} payload - The attributes to update in the product option. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. You can access the variant under the `options` property. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.products.updateOption(productId, optionId, { + * title: "Size" + * }) + * .then(({ product }) => { + * console.log(product.id); + * }) + */ updateOption( id: string, optionId: string, @@ -140,6 +418,13 @@ class AdminProductsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a product option. If there are product variants that use this product option, they must be deleted before deleting the product option. + * @param {string} id - The ID of the product that the option belongs to. + * @param {string} optionId - The ID of the product option. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + */ deleteOption( id: string, optionId: string, diff --git a/packages/medusa-js/src/resources/admin/publishable-api-keys.ts b/packages/medusa-js/src/resources/admin/publishable-api-keys.ts index e9b6563f54..971f3a1799 100644 --- a/packages/medusa-js/src/resources/admin/publishable-api-keys.ts +++ b/packages/medusa-js/src/resources/admin/publishable-api-keys.ts @@ -10,16 +10,46 @@ import { AdminPostPublishableApiKeySalesChannelsBatchReq, AdminDeletePublishableApiKeySalesChannelsBatchReq, GetPublishableApiKeySalesChannelsParams, - AdminSalesChannelsListRes, } from "@medusajs/medusa" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +import { AdminPublishableApiKeysListSalesChannelsRes } from "@medusajs/medusa" +/** + * This class is used to send requests to [Admin Publishable API Key API Routes](https://docs.medusajs.com/api/admin#publishable-api-keys). All its method + * are available in the JS Client under the `medusa.admin.publishableApiKeys` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Publishable API Keys can be used to scope Store API calls with an API key, determining what resources are retrieved when querying the API. + * For example, a publishable API key can be associated with one or more sales channels. When it is passed in the header of a request to the List Product store API Route, + * the sales channels are inferred from the key and only products associated with those sales channels are retrieved. + * Admins can manage publishable API keys and their associated resources. Currently, only Sales Channels are supported as a resource. + * + * Related Guide: [How to manage publishable API keys](https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys). + */ class AdminPublishableApiKeyResource extends BaseResource { + /** + * Retrieve a publishable API key's details. + * @param {string} id - The ID of the publishable API key. + * @privateRemarks The query parameter serves no purpose, so will leave this without a description until it's removed/fixed. + * @param {Record} query + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the publishable API key's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.retrieve(publishableApiKeyId) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id) + * }) + */ retrieve( id: string, - query?: {}, + query: Record = {}, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/publishable-api-keys/${id}` @@ -32,6 +62,40 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of publishable API keys. The publishable API keys can be filtered by fields such as `q` passed in `query`. The publishable API keys can also be paginated. + * @param {GetPublishableApiKeysParams} query - Filters and pagination configurations to apply on the retrieved publishable API keys. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of publishable API keys with pagination fields. + * + * @example + * To list publishable API keys: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.list() + * .then(({ publishable_api_keys, count, limit, offset }) => { + * console.log(publishable_api_keys) + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.list({ + * limit, + * offset + * }) + * .then(({ publishable_api_keys, count, limit, offset }) => { + * console.log(publishable_api_keys) + * }) + * ``` + */ list( query?: GetPublishableApiKeysParams, customHeaders: Record = {} @@ -46,6 +110,23 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Create a publishable API key. + * @param {AdminPostPublishableApiKeysReq} payload - The publishable API key to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the publishbale API key's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.create({ + * title + * }) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id) + * }) + */ create( payload: AdminPostPublishableApiKeysReq, customHeaders: Record = {} @@ -54,15 +135,48 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a publishable API key's details. + * @param {string} id - The ID of the publishable API key. + * @param {AdminPostPublishableApiKeysPublishableApiKeyReq} payload - The attributes to update in the publishable API key. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the publishbale API key's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.update(publishableApiKeyId, { + * title: "new title" + * }) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id) + * }) + */ update( id: string, payload: AdminPostPublishableApiKeysPublishableApiKeyReq, customHeaders: Record = {} - ) { + ): ResponsePromise { const path = `/admin/publishable-api-keys/${id}` return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a publishable API key. Associated resources, such as sales channels, are not deleted. + * @param {string} id - The ID of the publishable API key + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the delete operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.delete(publishableApiKeyId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) + */ delete( id: string, customHeaders: Record = {} @@ -71,6 +185,21 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Revoke a publishable API key. Revoking the publishable API Key can't be undone, and the key can't be used in future requests. + * @param {string} id - The ID of the publishable API key. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the publishbale API key's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.revoke(publishableApiKeyId) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id) + * }) + */ revoke( id: string, customHeaders: Record = {} @@ -79,6 +208,28 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("POST", path, {}, {}, customHeaders) } + /** + * Add a list of sales channels to a publishable API key. + * @param {string} id - The ID of the publishable API key. + * @param {AdminPostPublishableApiKeySalesChannelsBatchReq} payload - The sales channels to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the publishbale API key's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.addSalesChannelsBatch(publishableApiKeyId, { + * sales_channel_ids: [ + * { + * id: channelId + * } + * ] + * }) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id); + * }) + */ addSalesChannelsBatch( id: string, payload: AdminPostPublishableApiKeySalesChannelsBatchReq, @@ -88,6 +239,28 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Remove a list of sales channels from a publishable API key. This doesn't delete the sales channels and only removes the association between them and the publishable API key. + * @param {string} id - The ID of the publishable API key. + * @param {AdminDeletePublishableApiKeySalesChannelsBatchReq} payload - The sales channels to delete from the publishable API key. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the publishbale API key's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.deleteSalesChannelsBatch(publishableApiKeyId, { + * sales_channel_ids: [ + * { + * id: channelId + * } + * ] + * }) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id); + * }) + */ deleteSalesChannelsBatch( id: string, payload: AdminDeletePublishableApiKeySalesChannelsBatchReq, @@ -97,11 +270,27 @@ class AdminPublishableApiKeyResource extends BaseResource { return this.client.request("DELETE", path, payload, {}, customHeaders) } + /** + * List the sales channels associated with a publishable API key. The sales channels can be filtered by fields such as `q` passed in the `query` parameter. + * @param {string} id - The ID of the publishable API key. + * @param {GetPublishableApiKeySalesChannelsParams} query - Filters to apply on the retrieved sales channels. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of sales channels. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.publishableApiKeys.listSalesChannels() + * .then(({ sales_channels }) => { + * console.log(sales_channels.length) + * }) + */ listSalesChannels( id: string, query?: GetPublishableApiKeySalesChannelsParams, customHeaders: Record = {} - ): ResponsePromise { + ): ResponsePromise { let path = `/admin/publishable-api-keys/${id}/sales-channels` if (query) { diff --git a/packages/medusa-js/src/resources/admin/regions.ts b/packages/medusa-js/src/resources/admin/regions.ts index 248ba28ace..8f4d1c2103 100644 --- a/packages/medusa-js/src/resources/admin/regions.ts +++ b/packages/medusa-js/src/resources/admin/regions.ts @@ -14,12 +14,45 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Region API Routes](https://docs.medusajs.com/api/admin#regions). All its method + * are available in the JS Client under the `medusa.admin.regions` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Regions are different countries or geographical regions that the commerce store serves customers in. + * Admins can manage these regions, their providers, and more. + * + * Related Guide: [How to manage regions](https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions). + */ class AdminRegionsResource extends BaseResource { /** - * @description creates a region. - * @param payload - * @param customHeaders - * @returns created region. + * Create a region. + * @param {AdminPostRegionsReq} payload - The region to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.create({ + * name: "Europe", + * currency_code: "eur", + * tax_rate: 0, + * payment_providers: [ + * "manual" + * ], + * fulfillment_providers: [ + * "manual" + * ], + * countries: [ + * "DK" + * ] + * }) + * .then(({ region }) => { + * console.log(region.id); + * }) */ create( payload: AdminPostRegionsReq, @@ -30,11 +63,22 @@ class AdminRegionsResource extends BaseResource { } /** - * @description updates a region - * @param id id of the region to update. - * @param payload update to apply to region. - * @param customHeaders - * @returns the updated region. + * Update a region's details. + * @param {string} id - The region's ID. + * @param {AdminPostRegionsRegionReq} payload - The attributes to update in the region. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.update(regionId, { + * name: "Europe" + * }) + * .then(({ region }) => { + * console.log(region.id); + * }) */ update( id: string, @@ -46,10 +90,19 @@ class AdminRegionsResource extends BaseResource { } /** - * @description deletes a region - * @param id id of region to delete. - * @param customHeaders - * @returns Deleted response + * Delete a region. Associated resources, such as providers or currencies are not deleted. Associated tax rates are deleted. + * @param {string} id - The region's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.delete(regionId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -60,10 +113,19 @@ class AdminRegionsResource extends BaseResource { } /** - * @description get a region - * @param id id of the region to retrieve. - * @param customHeaders - * @returns the region with the given id + * Retrieve a region's details. + * @param {string} id - The region's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.retrieve(regionId) + * .then(({ region }) => { + * console.log(region.id); + * }) */ retrieve( id: string, @@ -74,10 +136,38 @@ class AdminRegionsResource extends BaseResource { } /** - * @description lists regions matching a query - * @param query query for searching regions - * @param customHeaders - * @returns a list of regions matching the query. + * Retrieve a list of Regions. The regions can be filtered by fields such as `created_at` passed in the `query` parameter. The regions can also be paginated. + * @param {AdminGetRegionsParams} query - Filters and pagination configurations to apply on the retrieved regions. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of regions with pagination fields. + * + * @example + * To list regions: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.list() + * .then(({ regions, limit, offset, count }) => { + * console.log(regions.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.list({ + * limit, + * offset + * }) + * .then(({ regions, limit, offset, count }) => { + * console.log(regions.length); + * }) + * ``` */ list( query?: AdminGetRegionsParams, @@ -94,11 +184,22 @@ class AdminRegionsResource extends BaseResource { } /** - * @description adds a country to the list of countries in a region - * @param id region id - * @param payload country data - * @param customHeaders - * @returns updated region + * Add a country to the list of countries in a region. + * @param {string} id - The region's ID. + * @param {AdminPostRegionsRegionCountriesReq} payload - The country to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.addCountry(regionId, { + * country_code: "dk" + * }) + * .then(({ region }) => { + * console.log(region.id); + * }) */ addCountry( id: string, @@ -110,11 +211,20 @@ class AdminRegionsResource extends BaseResource { } /** - * @description remove a country from a region's list of coutnries - * @param id region id - * @param country_code the 2 character ISO code for the Country. - * @param customHeaders - * @returns updated region + * Delete a country from the list of countries in a region. The country will still be available in the system, and it can be used in other regions. + * @param {string} id - The region's ID. + * @param {string} country_code - The code of the country to delete from the region. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.deleteCountry(regionId, "dk") + * .then(({ region }) => { + * console.log(region.id); + * }) */ deleteCountry( id: string, @@ -126,11 +236,22 @@ class AdminRegionsResource extends BaseResource { } /** - * @description adds a fulfillment provider to a region - * @param id region id - * @param payload fulfillment provider data - * @param customHeaders - * @returns updated region + * Add a fulfillment provider to the list of fulfullment providers in a region. + * @param {string} id - The region's ID. + * @param {AdminPostRegionsRegionFulfillmentProvidersReq} payload - The fulfillment provider to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.addFulfillmentProvider(regionId, { + * provider_id: "manual" + * }) + * .then(({ region }) => { + * console.log(region.id); + * }) */ addFulfillmentProvider( id: string, @@ -142,11 +263,20 @@ class AdminRegionsResource extends BaseResource { } /** - * @description remove a fulfillment provider from a region - * @param id region id - * @param provider_id the if of the fulfillment provider - * @param customHeaders - * @returns updated region + * Delete a fulfillment provider from a region. The fulfillment provider will still be available for usage in other regions. + * @param {string} id - The region's ID. + * @param {string} provider_id - The ID of the fulfillment provider to delete from the region. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.deleteFulfillmentProvider(regionId, "manual") + * .then(({ region }) => { + * console.log(region.id); + * }) */ deleteFulfillmentProvider( id: string, @@ -158,10 +288,19 @@ class AdminRegionsResource extends BaseResource { } /** - * @description retrieves the list of fulfillment options available in a region - * @param id region id - * @param customHeaders - * @returns list of fulfillment options + * Retrieve a list of fulfillment options available in a region. + * @param {string} id - The region's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of fulfillment options. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.retrieveFulfillmentOptions(regionId) + * .then(({ fulfillment_options }) => { + * console.log(fulfillment_options.length); + * }) */ retrieveFulfillmentOptions( id: string, @@ -172,11 +311,22 @@ class AdminRegionsResource extends BaseResource { } /** - * @description adds a payment provider to a region - * @param id region id - * @param payload payment provider data - * @param customHeaders - * @returns updated region + * Add a payment provider to the list of payment providers in a region. + * @param {string} id - The region's ID. + * @param {AdminPostRegionsRegionPaymentProvidersReq} payload - The payment provider to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.addPaymentProvider(regionId, { + * provider_id: "manual" + * }) + * .then(({ region }) => { + * console.log(region.id); + * }) */ addPaymentProvider( id: string, @@ -188,11 +338,20 @@ class AdminRegionsResource extends BaseResource { } /** - * @description removes a payment provider from a region - * @param id region id - * @param provider_id the id of the payment provider - * @param customHeaders - * @returns updated region + * Delete a payment provider from a region. The payment provider will still be available for usage in other regions. + * @param {string} id - The region's ID. + * @param {string} provider_id - The ID of the payment provider to delete from the region. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.regions.deletePaymentProvider(regionId, "manual") + * .then(({ region }) => { + * console.log(region.id); + * }) */ deletePaymentProvider( id: string, diff --git a/packages/medusa-js/src/resources/admin/reservations.ts b/packages/medusa-js/src/resources/admin/reservations.ts index 71153466fb..27fc674a4a 100644 --- a/packages/medusa-js/src/resources/admin/reservations.ts +++ b/packages/medusa-js/src/resources/admin/reservations.ts @@ -10,13 +10,33 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Reservation API Routes](https://docs.medusajs.com/api/admin#reservations). To use these API Routes, make sure to install the + * [@medusajs/inventory](https://docs.medusajs.com/modules/multiwarehouse/install-modules#inventory-module) module in your Medusa backend. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. The methods + * are available in the JS Client under the `medusa.admin.reservations` property. + * + * Reservations, provided by the [Inventory Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), are quantities of an item that are reserved, typically when an order is placed but not yet fulfilled. + * Reservations can be associated with any resources, but commonly with line items of an order. + * + * Related Guide: [How to manage item allocations in orders](https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders). + */ class AdminReservationsResource extends BaseResource { /** - * Get a reservation - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description gets a reservation - * @returns The reservation with the provided id + * Retrieve a reservation's details. + * @param {string} id - The reservation's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the reservation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.retrieve(reservationId) + * .then(({ reservation }) => { + * console.log(reservation.id); + * }) */ retrieve( id: string, @@ -27,11 +47,53 @@ class AdminReservationsResource extends BaseResource { } /** - * List reservations - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @description Lists reservations - * @returns A list of reservations matching the provided query + * Retrieve a list of reservations. The reservations can be filtered by fields such as `location_id` or `quantity` passed in the `query` parameter. The reservations can also be paginated. + * @param {AdminGetReservationsParams} query - Filters and pagination parameters to apply on the retrieved reservations. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of reservations with pagination fields. + * + * @example + * To list reservations: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.list() + * .then(({ reservations, count, limit, offset }) => { + * console.log(reservations.length) + * }) + * ``` + * + * To specify relations that should be retrieved within the reservations: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.list({ + * expand: "location" + * }) + * .then(({ reservations, count, limit, offset }) => { + * console.log(reservations.length) + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.list({ + * expand: "location", + * limit, + * offset + * }) + * .then(({ reservations, count, limit, offset }) => { + * console.log(reservations.length) + * }) + * ``` */ list( query?: AdminGetReservationsParams, @@ -48,11 +110,24 @@ class AdminReservationsResource extends BaseResource { } /** - * create a reservation - * @description create a reservation - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @returns the created reservation + * Create a reservation which can be associated with any resource, such as an order's line item. + * @param {AdminPostReservationsReq} payload - The reservation to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the reservation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.create({ + * line_item_id: "item_123", + * location_id: "loc_123", + * inventory_item_id: "iitem_123", + * quantity: 1 + * }) + * .then(({ reservation }) => { + * console.log(reservation.id); + * }); */ create( payload: AdminPostReservationsReq, @@ -63,11 +138,22 @@ class AdminReservationsResource extends BaseResource { } /** - * update a reservation - * @description update a reservation - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @returns The updated reservation + * Update a reservation's details. + * @param {string} id - The ID of the reservation. + * @param {AdminPostReservationsReservationReq} payload - The attributes to update in the reservation. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the reservation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.update(reservationId, { + * quantity: 3 + * }) + * .then(({ reservation }) => { + * console.log(reservation.id); + * }); */ update( id: string, @@ -79,11 +165,19 @@ class AdminReservationsResource extends BaseResource { } /** - * remove a reservation - * @description remove a reservation - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/inventory - * @returns reservation removal confirmation + * Delete a reservation. Associated resources, such as the line item, will not be deleted. + * @param {string} id - The ID of the reservation. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.reservations.delete(reservationId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }); */ delete( id: string, diff --git a/packages/medusa-js/src/resources/admin/return-reasons.ts b/packages/medusa-js/src/resources/admin/return-reasons.ts index 7411e2afbf..ea965209a2 100644 --- a/packages/medusa-js/src/resources/admin/return-reasons.ts +++ b/packages/medusa-js/src/resources/admin/return-reasons.ts @@ -8,12 +8,35 @@ import { import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Return Reason API Routes](https://docs.medusajs.com/api/admin#return-reasons). All its method + * are available in the JS Client under the `medusa.admin.returnReasons` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Return reasons are key-value pairs that are used to specify why an order return is being created. + * Admins can manage available return reasons, and they can be used by both admins and customers when creating a return. + * + * Related Guide: [How to manage return reasons](https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons). + */ class AdminReturnReasonsResource extends BaseResource { /** - * @description Creates a return reason. - * @param payload - * @param customHeaders - * @returns Created return reason. + * Create a return reason. + * @param {AdminPostReturnReasonsReq} payload - The return reason to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the return reason's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returnReasons.create({ + * label: "Damaged", + * value: "damaged" + * }) + * .then(({ return_reason }) => { + * console.log(return_reason.id); + * }); */ create( payload: AdminPostReturnReasonsReq, @@ -24,11 +47,22 @@ class AdminReturnReasonsResource extends BaseResource { } /** - * @description Updates a return reason - * @param id id of the return reason to update. - * @param payload update to apply to return reason. - * @param customHeaders - * @returns the updated return reason. + * Update a return reason's details. + * @param {string} id - The return reason's ID. + * @param {AdminPostReturnReasonsReasonReq} payload - The attributes to update in the return reason. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the return reason's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returnReasons.update(returnReasonId, { + * label: "Damaged" + * }) + * .then(({ return_reason }) => { + * console.log(return_reason.id); + * }); */ update( id: string, @@ -40,10 +74,19 @@ class AdminReturnReasonsResource extends BaseResource { } /** - * @description deletes a return reason - * @param id id of return reason to delete. - * @param customHeaders - * @returns Deleted response + * Delete a return reason. + * @param {string} id - The ID of the return reason. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returnReasons.delete(returnReasonId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }); */ delete( id: string, @@ -54,10 +97,19 @@ class AdminReturnReasonsResource extends BaseResource { } /** - * @description retrieves a return reason - * @param id id of the return reason to retrieve. - * @param customHeaders - * @returns the return reason with the given id + * Retrieve a return reason's details. + * @param {string} id - The return reason's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the return reason's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returnReasons.retrieve(returnReasonId) + * .then(({ return_reason }) => { + * console.log(return_reason.id); + * }); */ retrieve( id: string, @@ -68,9 +120,18 @@ class AdminReturnReasonsResource extends BaseResource { } /** - * @description Lists return reasons matching a query - * @returns a list of return reasons matching the query. - * @param customHeaders + * Retrieve a list of return reasons. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of return reasons. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returnReasons.list() + * .then(({ return_reasons }) => { + * console.log(return_reasons.length); + * }); */ list( customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/returns.ts b/packages/medusa-js/src/resources/admin/returns.ts index b7889cc935..d41a89dace 100644 --- a/packages/medusa-js/src/resources/admin/returns.ts +++ b/packages/medusa-js/src/resources/admin/returns.ts @@ -9,12 +9,33 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Return API Routes](https://docs.medusajs.com/api/admin#returns). All its method + * are available in the JS Client under the `medusa.admin.returns` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A return can be created by a customer or an admin to return items in an order. + * Admins can manage these returns and change their state. + * + * Related Guide: [How to manage returns](https://docs.medusajs.com/modules/orders/admin/manage-returns). + */ class AdminReturnsResource extends BaseResource { /** - * @description cancels a return - * @param id id of return to cancel - * @param customHeaders - * @returns the order for which the return was canceled + * Registers a return as canceled. The return can be associated with an order, claim, or swap. + * @param {string} id - The return's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the order associated with the return. If the return is associated with a claim or a swap, then it'll be the order + * that the claim or swap belongs to. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returns.cancel(returnId) + * .then(({ order }) => { + * console.log(order.id); + * }); */ cancel( id: string, @@ -25,11 +46,27 @@ class AdminReturnsResource extends BaseResource { } /** - * @description receive a return - * @param id id of the return to receive. - * @param payload items to receive and an optional refund amount - * @param customHeaders - * @returns the return + * Mark a return as received. This also updates the status of associated order, claim, or swap accordingly. + * @param {string} id - The return's ID. + * @param {AdminPostReturnsReturnReceiveReq} payload - The received return. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the return's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returns.receive(returnId, { + * items: [ + * { + * item_id, + * quantity: 1 + * } + * ] + * }) + * .then((data) => { + * console.log(data.return.id); + * }); */ receive( id: string, @@ -41,10 +78,38 @@ class AdminReturnsResource extends BaseResource { } /** - * @description lists returns matching a query - * @param query query for searching returns - * @param customHeaders - * @returns a list of returns matching the query + * Retrieve a list of Returns. The returns can be paginated. + * @param {AdminGetReturnsParams} query - Paignation configurations to be applied on the retrieved returns. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of returns with pagination fields. + * + * @example + * To list returns: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returns.list() + * .then(({ returns, limit, offset, count }) => { + * console.log(returns.length) + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.returns.list({ + * limit, + * offset + * }) + * .then(({ returns, limit, offset, count }) => { + * console.log(returns.length) + * }) + * ``` */ list( query?: AdminGetReturnsParams, diff --git a/packages/medusa-js/src/resources/admin/sales-channels.ts b/packages/medusa-js/src/resources/admin/sales-channels.ts index 68d7f5783e..7fd8c3edc6 100644 --- a/packages/medusa-js/src/resources/admin/sales-channels.ts +++ b/packages/medusa-js/src/resources/admin/sales-channels.ts @@ -14,12 +14,32 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Sales Channel API Routes](https://docs.medusajs.com/api/admin#sales-channels). All its method + * are available in the JS Client under the `medusa.admin.salesChannels` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A sales channel indicates a channel where products can be sold in. For example, a webshop or a mobile app. + * Admins can manage sales channels and the products available in them. + * + * Related Guide: [How to manage sales channels](https://docs.medusajs.com/modules/sales-channels/admin/manage). + */ class AdminSalesChannelsResource extends BaseResource { - /** retrieve a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description gets a sales channel - * @returns a medusa sales channel + /** + * Retrieve a sales channel's details. + * @param {string} salesChannelId - The sales channel's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.retrieve(salesChannelId) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id) + * }) */ retrieve( salesChannelId: string, @@ -29,9 +49,23 @@ class AdminSalesChannelsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } - /* * - * Create a medusa sales channel - * @returns the created channel + /** + * Create a sales channel. + * @param {AdminPostSalesChannelsReq} payload - The sales channel to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.create({ + * name: "App", + * description: "Mobile app" + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id); + * }) */ create( payload: AdminPostSalesChannelsReq, @@ -41,11 +75,23 @@ class AdminSalesChannelsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } - /** update a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description updates a sales channel - * @returns the updated medusa sales channel + /** + * Update a sales channel's details. + * @param {string} salesChannelId - The sales channel's ID. + * @param {AdminPostSalesChannelsSalesChannelReq} payload - The attributes to update in the sales channel. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.update(salesChannelId, { + * name: "App" + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id) + * }) */ update( salesChannelId: string, @@ -57,11 +103,53 @@ class AdminSalesChannelsResource extends BaseResource { } /** - * Retrieve a list of sales channels - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description Retrieve a list of sales channels - * @returns the list of sales channel as well as the pagination properties + * Retrieve a list of sales channels. The sales channels can be filtered by fields such as `q` or `name` passed in the `query` parameter. The sales channels can also be sorted or paginated. + * @param {AdminGetSalesChannelsParams} query - Filters and pagination configurations applied on the retrieved sales channels. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of sales channels with pagination fields. + * + * @example + * To list sales channels: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.list() + * .then(({ sales_channels, limit, offset, count }) => { + * console.log(sales_channels.length) + * }) + * ``` + * + * To specify relations that should be retrieved within the sales channels: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.list({ + * expand: "locations" + * }) + * .then(({ sales_channels, limit, offset, count }) => { + * console.log(sales_channels.length) + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.list({ + * expand: "locations", + * limit, + * offset + * }) + * .then(({ sales_channels, limit, offset, count }) => { + * console.log(sales_channels.length) + * }) + * ``` */ list( query?: AdminGetSalesChannelsParams, @@ -78,11 +166,19 @@ class AdminSalesChannelsResource extends BaseResource { } /** - * Delete a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description gets a sales channel - * @returns an deletion result + * Delete a sales channel. Associated products, stock locations, and other resources are not deleted. + * @param {string} salesChannelId - The sales channel's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.delete(salesChannelId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) */ delete( salesChannelId: string, @@ -93,11 +189,26 @@ class AdminSalesChannelsResource extends BaseResource { } /** - * Remove products from a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description Remove products from a sales channel - * @returns a medusa sales channel + * Remove a list of products from a sales channel. This doesn't delete the product. It only removes the association between the product and the sales channel. + * @param {string} salesChannelId - The sales channel's ID. + * @param {AdminDeleteSalesChannelsChannelProductsBatchReq} payload - The products to remove from the sales channel. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.removeProducts(salesChannelId, { + * product_ids: [ + * { + * id: productId + * } + * ] + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id) + * }) */ removeProducts( salesChannelId: string, @@ -109,11 +220,26 @@ class AdminSalesChannelsResource extends BaseResource { } /** - * Add products to a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description Add products to a sales channel - * @returns a medusa sales channel + * Add a list of products to a sales channel. + * @param {string} salesChannelId - The sales channel's ID. + * @param {AdminPostSalesChannelsChannelProductsBatchReq} payload - The products to add to the sales channel. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.addProducts(salesChannelId, { + * product_ids: [ + * { + * id: productId + * } + * ] + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id) + * }) */ addProducts( salesChannelId: string, @@ -125,11 +251,22 @@ class AdminSalesChannelsResource extends BaseResource { } /** - * Add a location to a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description Add a stock location to a SalesChannel - * @returns the Medusa SalesChannel + * Associate a stock location with a sales channel. + * @param {string} salesChannelId - The sales channel's ID. + * @param {AdminPostSalesChannelsChannelStockLocationsReq} payload - The stock location to associate with the sales channel. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.addLocation(salesChannelId, { + * location_id: "loc_123" + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id) + * }) */ addLocation( salesChannelId: string, @@ -141,11 +278,22 @@ class AdminSalesChannelsResource extends BaseResource { } /** - * remove a location from a sales channel - * @experimental This feature is under development and may change in the future. - * To use this feature please enable featureflag `sales_channels` in your medusa backend project. - * @description Remove a stock location from a SalesChannel - * @returns an deletion result + * Remove a stock location from a sales channel. This only removes the association between the stock location and the sales channel. It does not delete the stock location. + * @param {string} salesChannelId - The sales channel's ID. + * @param {AdminDeleteSalesChannelsChannelStockLocationsReq} payload - The stock location to remove from the sales channel. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the sales channel's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.salesChannels.removeLocation(salesChannelId, { + * location_id: "loc_id" + * }) + * .then(({ sales_channel }) => { + * console.log(sales_channel.id); + * }) */ removeLocation( salesChannelId: string, diff --git a/packages/medusa-js/src/resources/admin/shipping-options.ts b/packages/medusa-js/src/resources/admin/shipping-options.ts index 561318e74d..bdcf14419a 100644 --- a/packages/medusa-js/src/resources/admin/shipping-options.ts +++ b/packages/medusa-js/src/resources/admin/shipping-options.ts @@ -10,12 +10,39 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Shipping Option API Routes](https://docs.medusajs.com/api/admin#shipping-options). All its method + * are available in the JS Client under the `medusa.admin.shippingOptions` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A shipping option is used to define the available shipping methods during checkout or when creating a return. + * Admins can create an unlimited number of shipping options, each associated with a shipping profile and fulfillment provider, among other resources. + * + * Related Guide: [Shipping Option architecture](https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option). + */ class AdminShippingOptionsResource extends BaseResource { /** - * @description creates a shipping option. - * @param payload - * @param customHeaders - * @returns created shipping option. + * Create a shipping option. + * @param {AdminPostShippingOptionsReq} payload - The shipping option to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the shipping option's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingOptions.create({ + * name: "PostFake", + * region_id, + * provider_id, + * data: { + * }, + * price_type: "flat_rate" + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option.id) + * }) */ create( payload: AdminPostShippingOptionsReq, @@ -26,11 +53,29 @@ class AdminShippingOptionsResource extends BaseResource { } /** - * @description updates a shipping option - * @param id id of the shipping option to update. - * @param payload update to apply to shipping option. - * @param customHeaders - * @returns the updated shipping option. + * Update a shipping option's details. + * @param {string} id - The shipping option's ID. + * @param {AdminPostShippingOptionsOptionReq} payload - The attributes to update in the shipping option. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the shipping option's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingOptions.update(optionId, { + * name: "PostFake", + * requirements: [ + * { + * id, + * type: "max_subtotal", + * amount: 1000 + * } + * ] + * }) + * .then(({ shipping_option }) => { + * console.log(shipping_option.id) + * }) */ update( id: string, @@ -42,10 +87,19 @@ class AdminShippingOptionsResource extends BaseResource { } /** - * @description deletes a shipping option - * @param id id of shipping option to delete. - * @param customHeaders - * @returns deleted response + * Delete a shipping option. Once deleted, it can't be used when creating orders or returns. + * @param {string} id - The shipping option's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingOptions.delete(optionId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -56,10 +110,19 @@ class AdminShippingOptionsResource extends BaseResource { } /** - * @description get a shipping option - * @param id id of the shipping option to retrieve. - * @param customHeaders - * @returns the shipping option with the given id + * Retrieve a shipping option's details. + * @param {string} id - The shipping option's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the shipping option's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingOptions.retrieve(optionId) + * .then(({ shipping_option }) => { + * console.log(shipping_option.id); + * }) */ retrieve( id: string, @@ -70,10 +133,19 @@ class AdminShippingOptionsResource extends BaseResource { } /** - * @description lists shipping options matching a query - * @param query query for searching shipping options - * @param customHeaders - * @returns a list of shipping options matching the query. + * Retrieve a list of shipping options. The shipping options can be filtered by fields such as `region_id` or `is_return` passed in the `query` parameter. + * @param {AdminGetShippingOptionsParams} query - Filters to apply on the retrieved shipping options. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of shipping options. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingOptions.list() + * .then(({ shipping_options, count }) => { + * console.log(shipping_options.length); + * }) */ list( query?: AdminGetShippingOptionsParams, diff --git a/packages/medusa-js/src/resources/admin/shipping-profiles.ts b/packages/medusa-js/src/resources/admin/shipping-profiles.ts index a4ccf58cfc..b8214c62f9 100644 --- a/packages/medusa-js/src/resources/admin/shipping-profiles.ts +++ b/packages/medusa-js/src/resources/admin/shipping-profiles.ts @@ -8,7 +8,35 @@ import { import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Shipping Profile API Routes](https://docs.medusajs.com/api/admin#shipping-profiles). All its method + * are available in the JS Client under the `medusa.admin.shippingProfiles` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A shipping profile is used to group products that can be shipped in the same manner. + * They are created by the admin and they're not associated with a fulfillment provider. + * + * Related Guide: [Shipping Profile architecture](https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile). + */ class AdminShippingProfilesResource extends BaseResource { + /** + * Create a shipping profile. + * @param {AdminPostShippingProfilesReq} payload - The shipping profile to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the shipping profile's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingProfiles.create({ + * name: "Large Products" + * }) + * .then(({ shipping_profile }) => { + * console.log(shipping_profile.id); + * }) + */ create( payload: AdminPostShippingProfilesReq, customHeaders: Record = {} @@ -17,6 +45,24 @@ class AdminShippingProfilesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a shipping profile's details. + * @param {string} id - The shipping profile's ID. + * @param {AdminPostShippingProfilesProfileReq} payload - The attributes to update in the shipping profile. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the shipping profile's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingProfiles.update(shippingProfileId, { + * name: 'Large Products' + * }) + * .then(({ shipping_profile }) => { + * console.log(shipping_profile.id); + * }) + */ update( id: string, payload: AdminPostShippingProfilesProfileReq, @@ -26,6 +72,21 @@ class AdminShippingProfilesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Delete a shipping profile. Associated shipping options are deleted as well. + * @param {string} id - The shipping profile's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingProfiles.delete(profileId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( id: string, customHeaders: Record = {} @@ -34,6 +95,21 @@ class AdminShippingProfilesResource extends BaseResource { return this.client.request("DELETE", path, undefined, {}, customHeaders) } + /** + * Retrieve a shipping profile's details. + * @param {string} id - The shipping profile's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the shipping profile's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingProfiles.retrieve(profileId) + * .then(({ shipping_profile }) => { + * console.log(shipping_profile.id); + * }) + */ retrieve( id: string, customHeaders: Record = {} @@ -42,6 +118,20 @@ class AdminShippingProfilesResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of shipping profiles. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of shipping profiles. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.shippingProfiles.list() + * .then(({ shipping_profiles }) => { + * console.log(shipping_profiles.length); + * }) + */ list( customHeaders: Record = {} ): ResponsePromise { diff --git a/packages/medusa-js/src/resources/admin/stock-locations.ts b/packages/medusa-js/src/resources/admin/stock-locations.ts index 9ec0914902..eee0b389cc 100644 --- a/packages/medusa-js/src/resources/admin/stock-locations.ts +++ b/packages/medusa-js/src/resources/admin/stock-locations.ts @@ -10,13 +10,35 @@ import { ResponsePromise } from "../../typings" import BaseResource from "../base" import qs from "qs" +/** + * This class is used to send requests to [Admin Stock Location API Routes](https://docs.medusajs.com/api/admin#stock-locations). To use these API Routes, make sure to install the + * [@medusajs/stock-location](https://docs.medusajs.com/modules/multiwarehouse/install-modules#stock-location-module) module in your Medusa backend. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. The methods + * are available in the JS Client under the `medusa.admin.stockLocations` property. + * + * A stock location, provided by the [Stock Location module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module), indicates a physical address that stock-kept items, such as physical products, can be stored in. + * An admin can create and manage available stock locations. + * + * Related Guide: [How to manage stock locations](https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations). + */ class AdminStockLocationsResource extends BaseResource { /** - * Create a Stock Location - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/stock-location - * @description gets a medusa Stock Location - * @returns a medusa Stock Location + * Create a stock location. + * @param {AdminPostStockLocationsReq} payload - The stock location to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the stock location's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.create({ + * name: "Main Warehouse", + * }) + * .then(({ stock_location }) => { + * console.log(stock_location.id); + * }) */ create( payload: AdminPostStockLocationsReq, @@ -27,11 +49,19 @@ class AdminStockLocationsResource extends BaseResource { } /** - * Retrieve a Stock Location - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/stock-location - * @description gets a medusa Stock Location - * @returns a medusa Stock Location + * Retrieve a stock location's details. + * @param {string} itemId - The stock location's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the stock location's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.retrieve(stockLocationId) + * .then(({ stock_location }) => { + * console.log(stock_location.id); + * }) */ retrieve( itemId: string, @@ -42,11 +72,22 @@ class AdminStockLocationsResource extends BaseResource { } /** - * Update a Stock Location - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/stock-location - * @description updates a Stock Location - * @returns the updated medusa Stock Location + * Update a stock location's details. + * @param {string} stockLocationId - The stock location's ID. + * @param {AdminPostStockLocationsLocationReq} payload - The attributes to be updated in the stock location. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the stock location's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.update(stockLocationId, { + * name: 'Main Warehouse' + * }) + * .then(({ stock_location }) => { + * console.log(stock_location.id); + * }) */ update( stockLocationId: string, @@ -58,10 +99,19 @@ class AdminStockLocationsResource extends BaseResource { } /** - * Delete a Stock Location - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/stock-location - * @description deletes a Stock Location + * Delete a stock location. + * @param {string} id - The stock location's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.delete(stockLocationId) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) */ delete( id: string, @@ -72,11 +122,54 @@ class AdminStockLocationsResource extends BaseResource { } /** - * Retrieve a list of Stock Locations - * @experimental This feature is under development and may change in the future. - * To use this feature please install @medusajs/stock-location - * @description Retrieve a list of Stock Locations - * @returns the list of Stock Locations as well as the pagination properties + * Retrieve a list of stock locations. The stock locations can be filtered by fields such as `name` or `created_at` passed in the `query` parameter. + * The stock locations can also be sorted or paginated. + * @param {AdminGetStockLocationsParams} query - Filters and pagination configurations to apply on the retrieved stock locations. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of stock locations with pagination fields. + * + * @example + * To list stock locations: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.list() + * .then(({ stock_locations, limit, offset, count }) => { + * console.log(stock_locations.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the stock locations: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.list({ + * expand: "address" + * }) + * .then(({ stock_locations, limit, offset, count }) => { + * console.log(stock_locations.length); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.stockLocations.list({ + * expand: "address", + * limit, + * offset + * }) + * .then(({ stock_locations, limit, offset, count }) => { + * console.log(stock_locations.length); + * }) + * ``` */ list( query?: AdminGetStockLocationsParams, diff --git a/packages/medusa-js/src/resources/admin/store.ts b/packages/medusa-js/src/resources/admin/store.ts index 4e18118a17..2c0f554432 100644 --- a/packages/medusa-js/src/resources/admin/store.ts +++ b/packages/medusa-js/src/resources/admin/store.ts @@ -8,12 +8,32 @@ import { import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Store API Routes](https://docs.medusajs.com/api/admin#store). All its method + * are available in the JS Client under the `medusa.admin.store` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A store indicates the general configurations and details about the commerce store. By default, there's only one store in the Medusa backend. + * Admins can manage the store and its details or configurations. + */ class AdminStoresResource extends BaseResource { /** - * @description Updates the store - * @param payload update to apply to the store. - * @param customHeaders - * @returns the updated store. + * Update the store's details. + * @param {AdminPostStoreReq} payload - The attributes to update in the store. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the store's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.store.update({ + * name: "Medusa Store" + * }) + * .then(({ store }) => { + * console.log(store.id); + * }) */ update( payload: AdminPostStoreReq, @@ -24,10 +44,20 @@ class AdminStoresResource extends BaseResource { } /** - * @description adds a currency to the store. - * @param currency_code code of the currency to add - * @param customHeaders - * @returns updated store. + * Add a currency code to the available currencies in a store. This doesn't create new currencies, as currencies are defined within the Medusa backend. + * To create a currency, you can [create a migration](https://docs.medusajs.com/development/entities/migrations/create) that inserts the currency into the database. + * @param {string} currency_code - The code of the currency to add to the store. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the store's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.store.addCurrency("eur") + * .then(({ store }) => { + * console.log(store.currencies); + * }) */ addCurrency( currency_code: string, @@ -38,10 +68,19 @@ class AdminStoresResource extends BaseResource { } /** - * @description deletes a currency from the available store currencies - * @param currency_code currency code of the currency to delete from the store. - * @param customHeaders - * @returns updated store + * Delete a currency code from the available currencies in a store. This doesn't completely delete the currency and it can be added again later to the store. + * @param {string} currency_code - The code of the currency to delete from the store. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the store's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.store.deleteCurrency("eur") + * .then(({ store }) => { + * console.log(store.currencies); + * }) */ deleteCurrency( currency_code: string, @@ -52,8 +91,18 @@ class AdminStoresResource extends BaseResource { } /** - * @description gets a medusa store - * @returns a medusa store + * Retrieve the store's details. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the store's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.store.retrieve() + * .then(({ store }) => { + * console.log(store.id); + * }) */ retrieve( customHeaders: Record = {} @@ -63,8 +112,18 @@ class AdminStoresResource extends BaseResource { } /** - * @description Lists the store's payment providers - * @returns a list of payment providers configured on the store + * Retrieve a list of available payment providers in a store. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of payment providers. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.store.listPaymentProviders() + * .then(({ payment_providers }) => { + * console.log(payment_providers.length); + * }) */ listPaymentProviders( customHeaders: Record = {} @@ -74,8 +133,18 @@ class AdminStoresResource extends BaseResource { } /** - * @description Lists the store's payment providers - * @returns a list of payment providers configured on the store + * Retrieve a list of available tax providers in a store. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of tax providers. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.store.listTaxProviders() + * .then(({ tax_providers }) => { + * console.log(tax_providers.length); + * }) */ listTaxProviders( customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/swaps.ts b/packages/medusa-js/src/resources/admin/swaps.ts index ecb65be180..a5df455055 100644 --- a/packages/medusa-js/src/resources/admin/swaps.ts +++ b/packages/medusa-js/src/resources/admin/swaps.ts @@ -7,7 +7,33 @@ import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Swap API Routes](https://docs.medusajs.com/api/admin#swaps). All its method + * are available in the JS Client under the `medusa.admin.swaps` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A swap is created by a customer or an admin to exchange an item with a new one. + * Creating a swap implicitely includes creating a return for the item being exchanged. + * + * Related Guide: [How to manage swaps](https://docs.medusajs.com/modules/orders/admin/manage-swaps) + */ class AdminSwapsResource extends BaseResource { + /** + * Retrieve a swap's details. + * @param {string} id - The swap's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the swap's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.swaps.retrieve(swapId) + * .then(({ swap }) => { + * console.log(swap.id); + * }) + */ retrieve( id: string, customHeaders: Record = {} @@ -16,6 +42,40 @@ class AdminSwapsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of swaps. The swaps can be paginated. + * @param {AdminGetSwapsParams} query - Pagination configurations to apply on the retrieved swaps. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of swaps with pagination fields. + * + * @example + * To list swaps: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.swaps.list() + * .then(({ swaps }) => { + * console.log(swaps.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.swaps.list({ + * limit, + * offset + * }) + * .then(({ swaps }) => { + * console.log(swaps.length); + * }) + * ``` + */ list( query?: AdminGetSwapsParams, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/tax-rates.ts b/packages/medusa-js/src/resources/admin/tax-rates.ts index 82de2e5efd..58d582c2a5 100644 --- a/packages/medusa-js/src/resources/admin/tax-rates.ts +++ b/packages/medusa-js/src/resources/admin/tax-rates.ts @@ -19,8 +19,56 @@ import { import qs from "qs" import { ResponsePromise } from "../../typings" import BaseResource from "../base" +import { AdminPostTaxRatesTaxRateProductsParams } from "@medusajs/medusa" +import { AdminPostTaxRatesTaxRateShippingOptionsParams } from "@medusajs/medusa" +import { AdminPostTaxRatesParams } from "@medusajs/medusa" +import { AdminPostTaxRatesTaxRateParams } from "@medusajs/medusa" +/** + * This class is used to send requests to [Admin Tax Rate API Routes](https://docs.medusajs.com/api/admin#tax-rates). All its method + * are available in the JS Client under the `medusa.admin.taxRates` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Each region has at least a default tax rate. Admins can create and manage additional tax rates that can be applied for certain conditions, such as for specific product types. + * + * Related Guide: [How to manage tax rates](https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates). + */ class AdminTaxRatesResource extends BaseResource { + /** + * Retrieve a tax rate's details. + * @param {string} id - The tax rate's ID. + * @param {AdminGetTaxRatesTaxRateParams} query - Configurations to apply on retrieved tax rates. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * A simple example that retrieves a tax rate by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.retrieve(taxRateId) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.retrieve(taxRateId, { + * expand: "shipping_options" + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + * ``` + */ retrieve( id: string, query?: AdminGetTaxRatesTaxRateParams, @@ -36,6 +84,55 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Retrieve a list of tax rates. The tax rates can be filtered by fields such as `name` or `rate` passed in the `query` parameter. The tax rates can also be paginated. + * @param {AdminGetTaxRatesParams} query - Filters and pagination configurations applied to the retrieved tax rates. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of tax rates with pagination fields. + * + * @example + * To list tax rates: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.list() + * .then(({ tax_rates, limit, offset, count }) => { + * console.log(tax_rates.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the tax rates: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.list({ + * expand: "shipping_options" + * }) + * .then(({ tax_rates, limit, offset, count }) => { + * console.log(tax_rates.length); + * }) + * ``` + * + * By default, only the first `50` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.list({ + * expand: "shipping_options", + * limit, + * offset + * }) + * .then(({ tax_rates, limit, offset, count }) => { + * console.log(tax_rates.length); + * }) + * ``` + */ list( query?: AdminGetTaxRatesParams, customHeaders: Record = {} @@ -50,9 +147,29 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Create a tax rate. + * @param {AdminPostTaxRatesReq} payload - The tax rate to create. + * @param {AdminPostTaxRatesParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.create({ + * code: "TEST", + * name: "New Tax Rate", + * region_id + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ create( payload: AdminPostTaxRatesReq, - query?: AdminGetTaxRatesTaxRateParams, + query?: AdminPostTaxRatesParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/tax-rates` @@ -65,10 +182,29 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Update a tax rate's details. + * @param {string} id - The tax rate's ID. + * @param {AdminPostTaxRatesTaxRateReq} payload - The attributes to update in the tax rate. + * @param {AdminPostTaxRatesTaxRateParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.update(taxRateId, { + * name: "New Tax Rate" + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ update( id: string, payload: AdminPostTaxRatesTaxRateReq, - query?: AdminGetTaxRatesTaxRateParams, + query?: AdminPostTaxRatesTaxRateParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/tax-rates/${id}` @@ -81,10 +217,31 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Add products to a tax rate. + * @param {string} id - The tax rate's ID. + * @param {AdminPostTaxRatesTaxRateProductsReq} payload - The products to add to the tax rate. + * @param {AdminPostTaxRatesTaxRateProductsParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.addProducts(taxRateId, { + * products: [ + * productId + * ] + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ addProducts( id: string, payload: AdminPostTaxRatesTaxRateProductsReq, - query?: AdminGetTaxRatesTaxRateParams, + query?: AdminPostTaxRatesTaxRateProductsParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/tax-rates/${id}/products/batch` @@ -97,6 +254,27 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Add product types to a tax rate. + * @param {string} id - The tax rate's ID. + * @param {AdminPostTaxRatesTaxRateProductTypesReq} payload - The product types to add to the tax rate. + * @param {AdminGetTaxRatesTaxRateParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.addProductTypes(taxRateId, { + * product_types: [ + * productTypeId + * ] + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ addProductTypes( id: string, payload: AdminPostTaxRatesTaxRateProductTypesReq, @@ -113,10 +291,31 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Add shipping options to a tax rate. + * @param {string} id - The tax rate's ID. + * @param {AdminPostTaxRatesTaxRateShippingOptionsReq} payload - The shipping options to add to the tax rate. + * @param {AdminPostTaxRatesTaxRateShippingOptionsParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.addShippingOptions(taxRateId, { + * shipping_options: [ + * shippingOptionId + * ] + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ addShippingOptions( id: string, payload: AdminPostTaxRatesTaxRateShippingOptionsReq, - query?: AdminGetTaxRatesTaxRateParams, + query?: AdminPostTaxRatesTaxRateShippingOptionsParams, customHeaders: Record = {} ): ResponsePromise { let path = `/admin/tax-rates/${id}/shipping-options/batch` @@ -129,6 +328,27 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Remove products from a tax rate. This only removes the association between the products and the tax rate. It does not delete the products. + * @param {string} id - The tax rate's ID. + * @param {AdminDeleteTaxRatesTaxRateProductsReq} payload - The products to remove from the tax rate. + * @param {AdminGetTaxRatesTaxRateParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.removeProducts(taxRateId, { + * products: [ + * productId + * ] + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ removeProducts( id: string, payload: AdminDeleteTaxRatesTaxRateProductsReq, @@ -145,6 +365,27 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("DELETE", path, payload, {}, customHeaders) } + /** + * Remove product types from a tax rate. This only removes the association between the product types and the tax rate. It does not delete the product types. + * @param {string} id - The tax rate's ID. + * @param {AdminDeleteTaxRatesTaxRateProductTypesReq} payload - The product types to remove from the tax rate. + * @param {AdminGetTaxRatesTaxRateParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.removeProductTypes(taxRateId, { + * product_types: [ + * productTypeId + * ] + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ removeProductTypes( id: string, payload: AdminDeleteTaxRatesTaxRateProductTypesReq, @@ -161,6 +402,27 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("DELETE", path, payload, {}, customHeaders) } + /** + * Remove shipping options from a tax rate. This only removes the association between the shipping options and the tax rate. It does not delete the shipping options. + * @param {string} id - The tax rate's ID. + * @param {AdminDeleteTaxRatesTaxRateShippingOptionsReq} payload - The shipping options to remove from the tax rate. + * @param {AdminGetTaxRatesTaxRateParams} query - Configurations to apply on the retrieved tax rate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the tax rate's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.removeShippingOptions(taxRateId, { + * shipping_options: [ + * shippingOptionId + * ] + * }) + * .then(({ tax_rate }) => { + * console.log(tax_rate.id); + * }) + */ removeShippingOptions( id: string, payload: AdminDeleteTaxRatesTaxRateShippingOptionsReq, @@ -177,6 +439,21 @@ class AdminTaxRatesResource extends BaseResource { return this.client.request("DELETE", path, payload, {}, customHeaders) } + /** + * Delete a tax rate. Resources associated with the tax rate, such as products or product types, are not deleted. + * @param {string} id - The tax rate's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.taxRates.delete(taxRateId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( id: string, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/uploads.ts b/packages/medusa-js/src/resources/admin/uploads.ts index 8dab2e3a82..c5e3b79045 100644 --- a/packages/medusa-js/src/resources/admin/uploads.ts +++ b/packages/medusa-js/src/resources/admin/uploads.ts @@ -8,15 +8,38 @@ import { import { AdminCreateUploadPayload, ResponsePromise } from "../../typings" import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Upload API Routes](https://docs.medusajs.com/api/admin#uploads). All its method + * are available in the JS Client under the `medusa.admin.uploads` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * The methods in this class are used to upload any type of resources. For example, they can be used to upload CSV files that are used to import products into the store. + * + * Related Guide: [How to upload CSV file when importing a product](https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file). + */ class AdminUploadsResource extends BaseResource { + /** + * @ignore + * @privateRemarks No need to include this in the generated documentation. + */ private headers = { "Content-Type": "multipart/form-data", } /** - * @description Uploads at least one file to the specific fileservice that is installed in Medusa. - * @param file File or array of files to upload. - * @returns Uploaded file or files. + * Upload a file to a public bucket or storage. The file upload is handled by the file service installed on the Medusa backend. + * @param {AdminCreateUploadPayload} file - The file to upload. + * @returns {ResponsePromise} Resolves to the uploaded file details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.uploads.create(file) + * .then(({ uploads }) => { + * console.log(uploads.length); + * }) */ create(file: AdminCreateUploadPayload): ResponsePromise { const path = `/admin/uploads` @@ -27,9 +50,18 @@ class AdminUploadsResource extends BaseResource { } /** - * @description Uploads at least one file with ACL or a non-public bucket to the specific fileservice that is installed in Medusa. - * @param file File or array of files to upload. - * @returns Uploaded file or files. + * Upload a file to an ACL or a non-public bucket. The file upload is handled by the file service installed on the Medusa backend. + * @param {AdminCreateUploadPayload} file - The file to upload. + * @returns {ResponsePromise} Resolves to the uploaded file details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.uploads.createProtected(file) + * .then(({ uploads }) => { + * console.log(uploads.length); + * }) */ createProtected( file: AdminCreateUploadPayload @@ -41,6 +73,23 @@ class AdminUploadsResource extends BaseResource { return this.client.request("POST", path, payload, {}, this.headers) } + /** + * Delete an uploaded file from storage. The file is deleted using the installed file service on the Medusa backend. + * @param {AdminDeleteUploadsReq} payload - The uploaded file to delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.uploads.delete({ + * file_key + * }) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) + */ delete( payload: AdminDeleteUploadsReq, customHeaders: Record = {} @@ -50,6 +99,23 @@ class AdminUploadsResource extends BaseResource { return this.client.request("DELETE", path, payload, {}, customHeaders) } + /** + * Create and retrieve a presigned or public download URL for a file. The URL creation is handled by the file service installed on the Medusa backend. + * @param {AdminPostUploadsDownloadUrlReq} payload - The uploaded file to get a presigned download URL for. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the download URL details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.uploads.getPresignedDownloadUrl({ + * file_key + * }) + * .then(({ download_url }) => { + * console.log(download_url); + * }) + */ getPresignedDownloadUrl( payload: AdminPostUploadsDownloadUrlReq, customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/users.ts b/packages/medusa-js/src/resources/admin/users.ts index c6465d5297..826c247130 100644 --- a/packages/medusa-js/src/resources/admin/users.ts +++ b/packages/medusa-js/src/resources/admin/users.ts @@ -12,12 +12,39 @@ import { } from "../.." import BaseResource from "../base" +/** + * This class is used to send requests to [Admin User API Routes](https://docs.medusajs.com/api/admin#users). All its method + * are available in the JS Client under the `medusa.admin.users` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * A store can have more than one user, each having the same privileges. Admins can manage users, their passwords, and more. + * + * Related Guide: [How to manage users](https://docs.medusajs.com/modules/users/admin/manage-users). + */ class AdminUsersResource extends BaseResource { + /** - * @description resets password by re-sending password token. - * @param payload payload for generating reset-password token. - * @param customHeaders - * @returns + * Generate a password token for an admin user with a given email. This also triggers the `user.password_reset` event. So, if you have a Notification Service installed + * that can handle this event, a notification, such as an email, will be sent to the user. The token is triggered as part of the `user.password_reset` event's payload. + * That token must be used later to reset the password using the {@link resetPassword} method. + * @param {AdminResetPasswordTokenRequest} payload - The user's reset details. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when the token is generated successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.sendResetPasswordToken({ + * email: "user@example.com" + * }) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // error occurred + * }) */ sendResetPasswordToken( payload: AdminResetPasswordTokenRequest, @@ -28,10 +55,23 @@ class AdminUsersResource extends BaseResource { } /** - * @description resets the users password given the correct token. - * @param payload reset password information. - * @param customHeaders - * @returns + * Reset the password of an admin user using their reset password token. You must generate a reset password token first for the user using the {@link sendResetPasswordToken} method, + * then use that token to reset the password in this method. + * @param {AdminResetPasswordRequest} payload - The reset details. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the user's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.resetPassword({ + * token: "supersecrettoken", + * password: "supersecret" + * }) + * .then(({ user }) => { + * console.log(user.id); + * }) */ resetPassword( payload: AdminResetPasswordRequest, @@ -42,10 +82,19 @@ class AdminUsersResource extends BaseResource { } /** - * Retrieves a given user - * @param id id of the user - * @param customHeaders - * @returns the user + * Retrieve an admin user's details. + * @param {string} id - The user's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the user's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.retrieve(userId) + * .then(({ user }) => { + * console.log(user.id); + * }) */ retrieve( id: string, @@ -56,10 +105,22 @@ class AdminUsersResource extends BaseResource { } /** - * @description creates a user with the provided information - * @param payload user creation request body - * @param customHeaders - * @returns created user + * Create an admin user. The user has the same privileges as all admin users, and will be able to authenticate and perform admin functionalities right after creation. + * @param {AdminCreateUserPayload} payload - The user to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the user's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.create({ + * email: "user@example.com", + * password: "supersecret" + * }) + * .then(({ user }) => { + * console.log(user.id); + * }) */ create( payload: AdminCreateUserPayload, @@ -70,11 +131,22 @@ class AdminUsersResource extends BaseResource { } /** - * @description updates a given user - * @param id id of the user to update - * @param payload user update request body - * @param customHeaders - * @returns the updated user + * Update an admin user's details. + * @param {string} id - The user's ID. + * @param {AdminUpdateUserPayload} payload - The attributes to update in the user. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the user's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.update(userId, { + * first_name: "Marcellus" + * }) + * .then(({ user }) => { + * console.log(user.id); + * }) */ update( id: string, @@ -86,10 +158,19 @@ class AdminUsersResource extends BaseResource { } /** - * @description deletes a user - * @param id id of the user to be deleted - * @param customHeaders - * @returns delete response + * Delete a user. Once deleted, the user will not be able to authenticate or perform admin functionalities. + * @param {string} id - The user's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the deletion operation's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.delete(userId) + * .then(({ id, object, deleted }) => { + * console.log(id); + * }) */ delete( id: string, @@ -100,8 +181,18 @@ class AdminUsersResource extends BaseResource { } /** - * @description lists all users - * @returns a list of all users + * Retrieve all admin users. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of users. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.users.list() + * .then(({ users }) => { + * console.log(users.length); + * }) */ list( customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/admin/variants.ts b/packages/medusa-js/src/resources/admin/variants.ts index 694611fa6a..77a9d28af4 100644 --- a/packages/medusa-js/src/resources/admin/variants.ts +++ b/packages/medusa-js/src/resources/admin/variants.ts @@ -9,12 +9,66 @@ import qs from "qs" import { ResponsePromise } from "../.." import BaseResource from "../base" +/** + * This class is used to send requests to [Admin Product Variant API Routes](https://docs.medusajs.com/api/admin#product-variants). All its method + * are available in the JS Client under the `medusa.admin.variants` property. + * + * All methods in this class require {@link AdminAuthResource.createSession | user authentication}. + * + * Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product. + * Product variants can be managed through {@link AdminProductsResource}. + * + * Related Guide: [How to manage product variants](https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants). + */ class AdminVariantsResource extends BaseResource { /** - * List product variants - * @param query Query to filter variants by - * @param customHeaders custom headers - * @returns A list of variants satisfying the criteria of the query + * Retrieve a list of product variants. The product variant can be filtered by fields such as `id` or `title` passed in the `query` parameter. The product variant can also be paginated. + * @param {AdminGetVariantsParams} query - Filters and pagination configurations to apply on the retrieved product variants. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product variants with pagination fields. + * + * @example + * To list product variants: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.variants.list() + * .then(({ variants, limit, offset, count }) => { + * console.log(variants.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the product variants: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.variants.list({ + * expand: "options" + * }) + * .then(({ variants, limit, offset, count }) => { + * console.log(variants.length); + * }) + * ``` + * + * By default, only the first `100` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.variants.list({ + * expand: "options", + * limit, + * offset + * }) + * .then(({ variants, limit, offset, count }) => { + * console.log(variants.length); + * }) + * ``` */ list( query?: AdminGetVariantsParams, @@ -31,10 +85,38 @@ class AdminVariantsResource extends BaseResource { } /** - * Get a product variant - * @param id Query to filter variants by - * @param customHeaders custom headers - * @returns A list of variants satisfying the criteria of the query + * Retrieve a product variant's details. + * @param {string} id - The product variant's ID. + * @param {AdminGetVariantParams} query - Configurations to apply on the retrieved product variant. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product variant's details. + * + * @example + * A simple example that retrieves a product variant by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.variants.retrieve(variantId) + * .then(({ variant }) => { + * console.log(variant.id); + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.variants.retrieve(variantId, { + * expand: "options" + * }) + * .then(({ variant }) => { + * console.log(variant.id); + * }) + * ``` */ retrieve( id: string, @@ -52,10 +134,19 @@ class AdminVariantsResource extends BaseResource { } /** - * - * @param variantId id of the variant to fetch inventory for - * @param customHeaders custom headers - * @returns + * Retrieve the available inventory of a product variant. + * @param {string} variantId - The product variant's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the inventory details of the product variant. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.admin.variants.getInventory(variantId) + * .then(({ variant }) => { + * console.log(variant.inventory, variant.sales_channel_availability) + * }) */ getInventory( variantId: string, diff --git a/packages/medusa-js/src/resources/auth.ts b/packages/medusa-js/src/resources/auth.ts index b1e71008aa..0f381e553c 100644 --- a/packages/medusa-js/src/resources/auth.ts +++ b/packages/medusa-js/src/resources/auth.ts @@ -8,12 +8,34 @@ import { ResponsePromise } from "../typings" import JwtTokenManager from "../jwt-token-manager" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Auth API Routes](https://docs.medusajs.com/api/store#auth). All its method + * are available in the JS Client under the `medusa.auth` property. + * + * The methods in this class allows you to manage a customer's session, such as login or log out. + * You can send authenticated requests for a customer either using the Cookie header or using the JWT Token. + * When you log the customer in using the {@link authenticate} method, the JS client will automatically attach the + * cookie header in all subsequent requests. + * + * Related Guide: [How to implement customer profiles in your storefront](https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles). + */ class AuthResource extends BaseResource { /** - * @description Authenticates a customer using email and password combination - * @param {StorePostAuthReq} payload authentication payload - * @param customHeaders - * @return {ResponsePromise} + * Authenticate a customer using their email and password. If the customer is authenticated successfully, the cookie is automatically attached to subsequent requests sent with the JS Client. + * @param {StorePostAuthReq} payload - The credentials of the customer to authenticate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.auth.authenticate({ + * email: "user@example.com", + * password: "user@example.com" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ authenticate(payload: StorePostAuthReq, customHeaders: Record = {}): ResponsePromise { const path = `/store/auth` @@ -21,8 +43,17 @@ class AuthResource extends BaseResource { } /** - * @description Removes authentication session - * @return {ResponsePromise} + * Log out the customer and remove their authentication session. This method requires {@link AuthResource.authenticate | customer authentication}. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when customer is logged out successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.auth.deleteSession() + * .then(() => { + * // customer logged out successfully + * }) */ deleteSession(customHeaders: Record = {}): ResponsePromise { const path = `/store/auth` @@ -30,10 +61,19 @@ class AuthResource extends BaseResource { } /** - * @description Retrieves an authenticated session - * Usually used to check if authenticated session is alive. - * @param customHeaders - * @return {ResponsePromise} + * Retrieve the details of the logged-in customer. Can also be used to check if there is an authenticated customer. + * This method requires {@link AuthResource.authenticate | customer authentication}. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.auth.getSession() + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ getSession(customHeaders: Record = {}): ResponsePromise { const path = `/store/auth` @@ -41,10 +81,15 @@ class AuthResource extends BaseResource { } /** - * @description Check if email exists - * @param {string} email is required - * @param customHeaders - * @return {ResponsePromise} + * Check if the email is already used by another registered customer. Can be used to validate a new customer's email. + * @param {string} email - The email to check. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the result of the check. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.auth.exists("user@example.com") */ exists(email: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/auth/${email}` @@ -52,10 +97,21 @@ class AuthResource extends BaseResource { } /** - * @description Retrieves a new JWT access token - * @param {AdminPostAuthReq} payload - * @param customHeaders - * @return {ResponsePromise} + * Authenticate the customer and retrieve a JWT token to use for subsequent authenticated requests. + * @param {AdminPostAuthReq} payload - The credentials of the customer to authenticate. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the access token of the customer, if they're authenticated successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.auth.getToken({ + * email: 'user@example.com', + * password: 'supersecret' + * }) + * .then(({ access_token }) => { + * console.log(access_token); + * }) */ getToken( payload: StorePostAuthReq, diff --git a/packages/medusa-js/src/resources/carts.ts b/packages/medusa-js/src/resources/carts.ts index bc7fca37f6..ba159650ef 100644 --- a/packages/medusa-js/src/resources/carts.ts +++ b/packages/medusa-js/src/resources/carts.ts @@ -11,15 +11,37 @@ import { ResponsePromise } from "../typings" import BaseResource from "./base" import LineItemsResource from "./line-items" +/** + * This class is used to send requests to [Store Cart API Routes](https://docs.medusajs.com/api/store#carts). All its method + * are available in the JS Client under the `medusa.carts` property. + * + * A cart is a virtual shopping bag that customers can use to add items they want to purchase. + * A cart is then used to checkout and place an order. + * + * Related Guide: [How to implement cart functionality in your storefront](https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart). + */ class CartsResource extends BaseResource { + /** + * An instance of {@link LineItemsResource} used to send requests to line-item-related routes part of the [Store Cart API Routes](https://docs.medusajs.com/api/store#carts). + */ public lineItems = new LineItemsResource(this.client) /** - * Adds a shipping method to cart - * @param {string} cart_id Id of cart - * @param {StorePostCartsCartShippingMethodReq} payload Contains id of shipping option and optional data - * @param customHeaders - * @return {ResponsePromise} + * Add a shipping method to the cart. The validation of the `data` field is handled by the fulfillment provider of the chosen shipping option. + * @param {string} cart_id - The ID of the cart to add the shipping method to. + * @param {StorePostCartsCartShippingMethodReq} payload - The shipping method to add. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.addShippingMethod(cartId, { + * option_id + * }) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ addShippingMethod( cart_id: string, @@ -31,14 +53,22 @@ class CartsResource extends BaseResource { } /** - * Completes a cart. - * Payment authorization is attempted and if more work is required, we simply return the cart for further updates. - * If payment is authorized and order is not yet created, we make sure to do so. - * The completion of a cart can be performed idempotently with a provided header Idempotency-Key. - * If not provided, we will generate one for the request. - * @param {string} cart_id is required - * @param customHeaders - * @return {ResponsePromise} + * Complete a cart and place an order or create a swap, based on the cart's type. This includes attempting to authorize the cart's payment. + * If authorizing the payment requires more action, the cart will not be completed and the order will not be placed or the swap will not be created. + * An idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to + * the response. If an error occurs during cart completion or the request is interrupted for any reason, the cart completion can be retried by passing the idempotency + * key in the `Idempotency-Key` header. + * @param {string} cart_id - The ID of the cart to complete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the completion details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.complete(cartId) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ complete( cart_id: string, @@ -49,11 +79,20 @@ class CartsResource extends BaseResource { } /** - * Creates a cart - * @param {StorePostCartReq} payload is optional and can contain a region_id and items. - * The cart will contain the payload, if provided. Otherwise it will be empty - * @param customHeaders - * @return {ResponsePromise} + * Create a Cart. Although optional, specifying the cart's region and sales channel can affect the cart's pricing and + * the products that can be added to the cart respectively. So, make sure to set those early on and change them if necessary, such as when the customer changes their region. + * If a customer is logged in, make sure to pass its ID or email within the cart's details so that the cart is attached to the customer. + * @param {StorePostCartReq} payload - The cart to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the created cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.create() + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ create( payload?: StorePostCartReq, @@ -64,12 +103,19 @@ class CartsResource extends BaseResource { } /** - * Creates payment sessions. - * Initializes the payment sessions that can be used to pay for the items of the cart. - * This is usually called when a customer proceeds to checkout. - * @param {string} cart_id is required - * @param customHeaders - * @return {ResponsePromise} + * Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there's only one payment session created, + * it will be selected by default. The creation of the payment session uses the payment provider and may require sending requests to third-party services. + * @param {string} cart_id - The ID of the cart to create the payment sessions for. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.createPaymentSessions(cartId) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ createPaymentSessions( cart_id: string, @@ -80,11 +126,20 @@ class CartsResource extends BaseResource { } /** - * Removes a discount from cart. - * @param {string} cart_id is required - * @param {string} code discount code to remove - * @param customHeaders - * @return {ResponsePromise} + * Remove a Discount from a Cart. This only removes the application of the discount, and not completely deletes it. The totals will be re-calculated and the payment sessions + * will be refreshed after the removal. + * @param {string} cart_id - the ID of the cart to remove the discount from. + * @param {string} code - The code of the discount to remove from the cart. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.deleteDiscount(cartId, code) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ deleteDiscount( cart_id: string, @@ -96,12 +151,19 @@ class CartsResource extends BaseResource { } /** - * Removes a payment session from a cart. - * Can be useful in case a payment has failed - * @param {string} cart_id is required - * @param {string} provider_id the provider id of the session e.g. "stripe" - * @param customHeaders - * @return {ResponsePromise} + * Delete a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated. + * @param {string} cart_id - The ID of the cart to delete the payment session from. + * @param {string} provider_id - The ID of the payment provider that the session is associated with. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.deletePaymentSession(cartId, "manual") + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ deletePaymentSession( cart_id: string, @@ -113,11 +175,19 @@ class CartsResource extends BaseResource { } /** - * Refreshes a payment session. - * @param {string} cart_id is required - * @param {string} provider_id the provider id of the session e.g. "stripe" - * @param customHeaders - * @return {ResponsePromise} + * Refresh a Payment Session to ensure that it is in sync with the Cart. This is usually not necessary, but is provided for edge cases. + * @param {string} cart_id - The ID of the cart to refresh its payment session. + * @param {string} provider_id - The ID of the payment provider that's associated with the payment session. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.refreshPaymentSession(cartId, "manual") + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ refreshPaymentSession( cart_id: string, @@ -129,10 +199,18 @@ class CartsResource extends BaseResource { } /** - * Retrieves a cart - * @param {string} cart_id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Cart's details. This includes recalculating its totals. + * @param {string} cart_id - The cart's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.retrieve(cartId) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ retrieve( cart_id: string, @@ -143,11 +221,22 @@ class CartsResource extends BaseResource { } /** - * Refreshes a payment session. - * @param {string} cart_id is required - * @param {StorePostCartsCartPaymentSessionReq} payload the provider id of the session e.g. "stripe" - * @param customHeaders - * @return {ResponsePromise} + * Select the Payment Session that will be used to complete the cart. This is typically used when the customer chooses their preferred payment method during checkout. + * The totals of the cart will be recalculated. + * @param {string} cart_id - The cart's ID. + * @param {StorePostCartsCartPaymentSessionReq} payload - The associated payment provider. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.setPaymentSession(cartId, { + * provider_id: "manual" + * }) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ setPaymentSession( cart_id: string, @@ -159,11 +248,21 @@ class CartsResource extends BaseResource { } /** - * Updates a cart - * @param {string} cart_id is required - * @param {StorePostCartsCartReq} payload is required and can contain region_id, email, billing and shipping address - * @param customHeaders - * @return {ResponsePromise} + * Update a Cart's details. If the cart has payment sessions and the region was not changed, the payment sessions are updated. The cart's totals are also recalculated. + * @param {string} cart_id - The cart's ID. + * @param {StorePostCartsCartReq} payload - The attributes to update in the cart. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.update(cartId, { + * email: "user@example.com" + * }) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ update( cart_id: string, @@ -175,12 +274,25 @@ class CartsResource extends BaseResource { } /** - * Updates the payment method - * @param {string} cart_id is required - * @param {string} provider_id is required - * @param {StorePostCartsCartPaymentSessionUpdateReq} payload is required - * @param customHeaders - * @return {ResponsePromise} + * Update a Payment Session with additional data. This can be useful depending on the payment provider used. + * All payment sessions are updated and cart totals are recalculated afterwards. + * @param {string} cart_id - The cart's ID. + * @param {string} provider_id - The ID of the payment provider that the payment session is associated with. + * @param {StorePostCartsCartPaymentSessionUpdateReq} payload - The attributes to update in the payment session. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.updatePaymentSession(cartId, "manual", { + * data: { + * + * } + * }) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ updatePaymentSession( cart_id: string, diff --git a/packages/medusa-js/src/resources/collections.ts b/packages/medusa-js/src/resources/collections.ts index b661b250d7..f4fbcc9705 100644 --- a/packages/medusa-js/src/resources/collections.ts +++ b/packages/medusa-js/src/resources/collections.ts @@ -7,12 +7,27 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Product Collection API Routes](https://docs.medusajs.com/api/store#product-collections). All its method + * are available in the JS Client under the `medusa.collections` property. + * + * A product collection is used to organize products for different purposes such as marketing or discount purposes. For example, you can create a Summer Collection. + * Using the methods in this class, you can list or retrieve a collection's details and products. + */ class CollectionsResource extends BaseResource { /** - * @description Retrieves a single collection - * @param {string} id id of the collection - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a product collection's details. + * @param {string} id - The ID of the product collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.collections.retrieve(collectionId) + * .then(({ collection }) => { + * console.log(collection.id); + * }) */ retrieve(id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/collections/${id}` @@ -20,10 +35,37 @@ class CollectionsResource extends BaseResource { } /** - * @description Retrieves a list of collections - * @param {string} query is optional. Can contain a limit and offset for the returned list - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of product collections. The product collections can be filtered by fields such as `handle` or `created_at` passed in the `query` parameter. + * The product collections can also be paginated. + * @param {StoreGetCollectionsParams} query - Filters and pagination configurations to apply on the retrieved product collections. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product collections with pagination fields. + * + * @example + * To list product collections: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.collections.list() + * .then(({ collections, limit, offset, count }) => { + * console.log(collections.length); + * }) + * ``` + * + * By default, only the first `10` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.collections.list({ + * limit, + * offset + * }) + * .then(({ collections, limit, offset, count }) => { + * console.log(collections.length); + * }) + * ``` */ list( query?: StoreGetCollectionsParams, diff --git a/packages/medusa-js/src/resources/customers.ts b/packages/medusa-js/src/resources/customers.ts index 5cb5da5dd0..ab95f80da5 100644 --- a/packages/medusa-js/src/resources/customers.ts +++ b/packages/medusa-js/src/resources/customers.ts @@ -13,15 +13,44 @@ import AddressesResource from "./addresses" import BaseResource from "./base" import PaymentMethodsResource from "./payment-methods" +/** + * This class is used to send requests to [Store Customer API Routes](https://docs.medusajs.com/api/store#customers_postcustomers). All its method + * are available in the JS Client under the `medusa.customers` property. + * + * A customer can register and manage their information such as addresses, orders, payment methods, and more. + * + * Related Guide: [How to implement customer profiles in your storefront](https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles). + */ class CustomerResource extends BaseResource { + /** + * An instance of {@link PaymentMethodsResource} used to send requests to payment-related routes part of the [Store Customer API Routes](https://docs.medusajs.com/api/store#customers_postcustomers). + */ public paymentMethods = new PaymentMethodsResource(this.client) + /** + * An instance of {@link AddressesResource} used to send requests to address-related routes part of the [Store Customer API Routes](https://docs.medusajs.com/api/store#customers_postcustomers). + */ public addresses = new AddressesResource(this.client) /** - * Creates a customer - * @param {StorePostCustomersReq} payload information of customer - * @param customHeaders - * @return { ResponsePromise} + * Register a new customer. This will also automatically authenticate the customer and set their login session in the response Cookie header. + * Subsequent requests sent with the JS client are sent with the Cookie session automatically. + * @param {StorePostCustomersReq} payload - The details of the customer to be created. + * @param {string} query - Filters and pagination configurations to apply on the retrieved product collections. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns { ResponsePromise} Resolves to the created customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.customers.create({ + * first_name: "Alec", + * last_name: "Reynolds", + * email: "user@example.com", + * password: "supersecret" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ create( payload: StorePostCustomersReq, @@ -32,9 +61,18 @@ class CustomerResource extends BaseResource { } /** - * Retrieves the customer that is currently logged - * @param customHeaders - * @return {ResponsePromise} + * Retrieve the logged-in customer's details. This method requires {@link AuthResource.authenticate | customer authentication}. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the logged-in customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.retrieve() + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ retrieve( customHeaders: Record = {} @@ -44,10 +82,21 @@ class CustomerResource extends BaseResource { } /** - * Updates a customer - * @param {StorePostCustomersCustomerReq} payload information to update customer with - * @param customHeaders - * @return {ResponsePromise} + * Update the logged-in customer's details. This method requires {@link AuthResource.authenticate | customer authentication}. + * @param {StorePostCustomersCustomerReq} payload - The attributes to update in the logged-in customer. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the logged-in customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.update({ + * first_name: "Laury" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ update( payload: StorePostCustomersCustomerReq, @@ -58,10 +107,20 @@ class CustomerResource extends BaseResource { } /** - * Retrieve customer orders - * @param {StoreGetCustomersCustomerOrdersParams} params optional params to retrieve orders - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of the logged-in customer's orders. The orders can be filtered by fields such as `status` or `fulfillment_status`. The orders can also be paginated. + * This method requires {@link AuthResource.authenticate | customer authentication}. + * @param {StoreGetCustomersCustomerOrdersParams} params - Filters and pagination configurations to apply on the retrieved orders. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of orders with pagination fields. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.listOrders() + * .then(({ orders, limit, offset, count }) => { + * console.log(orders); + * }) */ listOrders( params?: StoreGetCustomersCustomerOrdersParams, @@ -78,10 +137,23 @@ class CustomerResource extends BaseResource { } /** - * Resets customer password - * @param {StorePostCustomersCustomerPasswordTokenReq} payload info used to reset customer password - * @param customHeaders - * @return {ResponsePromise} + * Reset a customer's password using a password token created by a previous request using the {@link generatePasswordToken} method. If the password token expired, + * you must create a new one. + * @param {StorePostCustomersResetPasswordReq} payload - The necessary details to reset the password. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the customer's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.customers.resetPassword({ + * email: "user@example.com", + * password: "supersecret", + * token: "supersecrettoken" + * }) + * .then(({ customer }) => { + * console.log(customer.id); + * }) */ resetPassword( payload: StorePostCustomersResetPasswordReq, @@ -92,11 +164,24 @@ class CustomerResource extends BaseResource { } /** - * Generates a reset password token, which can be used to reset the password. - * The token is not returned but should be sent out to the customer in an email. - * @param {StorePostCustomersCustomerPasswordTokenReq} payload info used to generate token - * @param customHeaders - * @return {ResponsePromise} + * Create a reset password token to be used when sending a request with the {@link resetPassword} method. This emits the event `customer.password_reset`. If a notification provider is + * installed in the Medusa backend and is configured to handle this event, a notification to the customer, such as an email, may be sent with reset instructions. + * @param {StorePostCustomersCustomerPasswordTokenReq} payload - The necessary details to create the reset password token. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when reset password token is created successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.customers.generatePasswordToken({ + * email: "user@example.com" + * }) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // failed + * }) */ generatePasswordToken( payload: StorePostCustomersCustomerPasswordTokenReq, diff --git a/packages/medusa-js/src/resources/gift-cards.ts b/packages/medusa-js/src/resources/gift-cards.ts index 8b36bc2107..37a3b3f279 100644 --- a/packages/medusa-js/src/resources/gift-cards.ts +++ b/packages/medusa-js/src/resources/gift-cards.ts @@ -2,12 +2,29 @@ import { StoreGiftCardsRes } from "@medusajs/medusa" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Gift Card API Routes](https://docs.medusajs.com/api/store#gift-cards). All its method + * are available in the JS Client under the `medusa.giftCards` property. + * + * Customers can use gift cards during checkout to deduct the gift card's balance from the checkout total. + * The methods in this class allow retrieving a gift card's details by its code. A gift card can be applied to a cart using {@link CartsResource}. + * + * Related Guide: [How to use gift cards in a storefront](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards). + */ class GiftCardsResource extends BaseResource { /** - * @description Retrieves a single GiftCard - * @param {string} code code of the gift card - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Gift Card's details by its associated unique code. + * @param {string} code - The code of the gift card. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the gift card. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.giftCards.retrieve(code) + * .then(({ gift_card }) => { + * console.log(gift_card.id); + * }) */ retrieve(code: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/gift-cards/${code}` diff --git a/packages/medusa-js/src/resources/line-items.ts b/packages/medusa-js/src/resources/line-items.ts index b8c1d2dcd5..12cbcd97fc 100644 --- a/packages/medusa-js/src/resources/line-items.ts +++ b/packages/medusa-js/src/resources/line-items.ts @@ -6,13 +6,28 @@ import { import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to Line Item API Routes part of the [Store Cart API Routes](https://docs.medusajs.com/api/store#carts). All its method + * are available in the JS Client under the `medusa.carts.lineItems` property. + */ class LineItemsResource extends BaseResource { /** - * Creates a line-item for a cart - * @param {string} cart_id id of cart - * @param {StorePostCartsCartLineItemsReq} payload details needed to create a line-item - * @param customHeaders - * @return {ResponsePromise} + * Generates a Line Item with a given Product Variant and adds it to the Cart + * @param {string} cart_id - The cart's ID. + * @param {StorePostCartsCartLineItemsReq} payload - The line item to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the associated cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.lineItems.create(cart_id, { + * variant_id, + * quantity: 1 + * }) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ create( cart_id: string, @@ -23,13 +38,22 @@ class LineItemsResource extends BaseResource { } /** - * Updates a line-item. - * Only quantity updates are allowed - * @param {string} cart_id id of cart - * @param {string} line_id id of item to update - * @param {StorePostCartsCartLineItemsItemReq} payload details needed to update a line-item - * @param customHeaders - * @return {ResponsePromise} + * Update a line item's data. + * @param {string} cart_id - The ID of the line item's cart. + * @param {string} line_id - The ID of the line item to update. + * @param {StorePostCartsCartLineItemsItemReq} payload - The data to update in the line item. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the associated cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.lineItems.update(cartId, lineId, { + * quantity: 1 + * }) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ update( cart_id: string, @@ -41,11 +65,19 @@ class LineItemsResource extends BaseResource { } /** - * Remove a line-item from a cart - * @param {string} cart_id id of cart - * @param {string} line_id id of item to remove - * @param customHeaders - * @return {ResponsePromise} + * Delete a line item from a cart. The payment sessions will be updated and the totals will be recalculated. + * @param {string} cart_id - The ID of the line item's cart. + * @param {string} line_id - The ID of the line item to delete. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the associated cart's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.carts.lineItems.delete(cartId, lineId) + * .then(({ cart }) => { + * console.log(cart.id); + * }) */ delete(cart_id: string, line_id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/carts/${cart_id}/line-items/${line_id}` diff --git a/packages/medusa-js/src/resources/order-edits.ts b/packages/medusa-js/src/resources/order-edits.ts index 966a36b12b..9057e9af38 100644 --- a/packages/medusa-js/src/resources/order-edits.ts +++ b/packages/medusa-js/src/resources/order-edits.ts @@ -5,7 +5,30 @@ import { import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Order Edits API Routes](https://docs.medusajs.com/api/store#order-edits). All its method + * are available in the JS Client under the `medusa.orderEdits` property. + * + * Order edits are changes made to items in an order such as adding, updating their quantity, or deleting them. Order edits are created by the admin. + * A customer can review order edit requests created by an admin and confirm or decline them. + * + * Related Guide: [How to handle order edits in a storefront](https://docs.medusajs.com/modules/orders/storefront/handle-order-edits). + */ class OrderEditsResource extends BaseResource { + /** + * Retrieve an Order Edit's details. + * @param {string} id - The ID of the order edit. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.orderEdits.retrieve(orderEditId) + * .then(({ order_edit }) => { + * console.log(order_edit.id); + * }) + */ retrieve( id: string, customHeaders: Record = {} @@ -14,16 +37,45 @@ class OrderEditsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Decline an Order Edit. The changes are not reflected on the original order. + * @param {string} id - The ID of the order edit. + * @param {StorePostOrderEditsOrderEditDecline} payload - The decline details. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.orderEdits.decline(orderEditId) + * .then(({ order_edit }) => { + * console.log(order_edit.id); + * }) + */ decline( id: string, payload: StorePostOrderEditsOrderEditDecline, customHeaders: Record = {} - ) { + ): ResponsePromise { const path = `/store/order-edits/${id}/decline` return this.client.request("POST", path, payload, {}, customHeaders) } - complete(id: string, customHeaders: Record = {}) { + /** + * Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the {@link PaymentCollectionsResource} routes. + * @param {string} id - The ID of the order edit. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the order edit's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.orderEdits.complete(orderEditId) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) + */ + complete(id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/order-edits/${id}/complete` return this.client.request("POST", path, undefined, {}, customHeaders) } diff --git a/packages/medusa-js/src/resources/orders.ts b/packages/medusa-js/src/resources/orders.ts index e2b73385e1..475379349e 100644 --- a/packages/medusa-js/src/resources/orders.ts +++ b/packages/medusa-js/src/resources/orders.ts @@ -8,12 +8,29 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Order API Routes](https://docs.medusajs.com/api/store#orders). All its method + * are available in the JS Client under the `medusa.orders` property. + * + * Orders are purchases made by customers, typically through a storefront. + * Orders are placed and created using {@link CartsResource}. The methods in this class allow retrieving and claiming orders. + * + * Related Guide: [How to retrieve order details in a storefront](https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details). + */ class OrdersResource extends BaseResource { /** - * @description Retrieves an order - * @param {string} id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve an Order's details. + * @param {string} id - The order's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the order. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.orders.retrieve(orderId) + * .then(({ order }) => { + * console.log(order.id); + * }) */ retrieve( id: string, @@ -24,10 +41,18 @@ class OrdersResource extends BaseResource { } /** - * @description Retrieves an order by cart id - * @param {string} cart_id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve an order's details by the ID of the cart that was used to create the order. + * @param {string} cart_id - The cart's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the order. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.orders.retrieveByCartId(cartId) + * .then(({ order }) => { + * console.log(order.id); + * }) */ retrieveByCartId( cart_id: string, @@ -38,10 +63,21 @@ class OrdersResource extends BaseResource { } /** - * @description Look up an order using order details - * @param {StoreGetOrdersParams} payload details used to look up the order - * @param customHeaders - * @return {ResponsePromise} + * Look up an order using filters. If the filters don't narrow down the results to a single order, a `404` response is returned with no orders. + * @param {StoreGetOrdersParams} payload - Filters used to retrieve the order. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the details of the order. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.orders.lookupOrder({ + * display_id: 1, + * email: "user@example.com" + * }) + * .then(({ order }) => { + * console.log(order.id); + * }) */ lookupOrder( payload: StoreGetOrdersParams, @@ -56,10 +92,26 @@ class OrdersResource extends BaseResource { } /** - * @description Request access to a list of orders - * @param {string[]} payload display ids of orders to request - * @param customHeaders - * @return {ResponsePromise} + * Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the {@link confirmRequest} method. + * This also emits the event `order-update-token.created`. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email, + * the customer should receive instructions on how to finalize their claim ownership. + * @param {StorePostCustomersCustomerOrderClaimReq} payload - The orders to claim. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when the request is created successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.orders.requestCustomerOrders({ + * order_ids, + * }) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // an error occurred + * }) */ requestCustomerOrders( payload: StorePostCustomersCustomerOrderClaimReq, @@ -70,10 +122,24 @@ class OrdersResource extends BaseResource { } /** - * @description Grant access to a list of orders - * @param {string} payload signed token to grant access - * @param customHeaders - * @return {ResponsePromise} + * Verify the claim order token provided to the customer when they request ownership of an order. + * @param {StorePostCustomersCustomerAcceptClaimReq} payload - The claim order to verify. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves when the claim order is verified successfully. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.orders.confirmRequest( + * token, + * ) + * .then(() => { + * // successful + * }) + * .catch(() => { + * // an error occurred + * }) */ confirmRequest( payload: StorePostCustomersCustomerAcceptClaimReq, diff --git a/packages/medusa-js/src/resources/payment-collections.ts b/packages/medusa-js/src/resources/payment-collections.ts index 4bd30e9468..d6609f88d5 100644 --- a/packages/medusa-js/src/resources/payment-collections.ts +++ b/packages/medusa-js/src/resources/payment-collections.ts @@ -10,7 +10,48 @@ import { ResponsePromise } from "../typings" import BaseResource from "./base" import qs from "qs" +/** + * This class is used to send requests to [Store Payment Collection API Routes](https://docs.medusajs.com/api/store#payment-collections). All its method + * are available in the JS Client under the `medusa.paymentCollections` property. + * + * A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments. + */ class PaymentCollectionsResource extends BaseResource { + + /** + * Retrieve a Payment Collection's details. + * @param {string} id - The ID of the payment collection. + * @param {StoreGetPaymentCollectionsParams} query - Configurations to apply on the retrieved payment collection. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * A simple example that retrieves a payment collection by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.retrieve(paymentCollectionId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.retrieve(paymentCollectionId, { + * expand: "region" + * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) + * ``` + */ retrieve( id: string, query?: StoreGetPaymentCollectionsParams, @@ -26,6 +67,22 @@ class PaymentCollectionsResource extends BaseResource { return this.client.request("GET", path, undefined, {}, customHeaders) } + /** + * Authorize a Payment Session of a Payment Collection. + * @param {string} id - The ID of the payment collection. + * @param {string} session_id - The ID of the payment session. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.authorize(paymentId, sessionId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }) + */ authorizePaymentSession( id: string, session_id: string, @@ -35,6 +92,22 @@ class PaymentCollectionsResource extends BaseResource { return this.client.request("POST", path, undefined, {}, customHeaders) } + /** + * Authorize the Payment Sessions of a Payment Collection. + * @param {string} id - The ID of the payment collection. + * @param {StorePostPaymentCollectionsBatchSessionsAuthorizeReq} payload - The list of payment session IDs to authorize. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.authorize(paymentId) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }) + */ authorizePaymentSessionsBatch( id: string, payload: StorePostPaymentCollectionsBatchSessionsAuthorizeReq, @@ -44,6 +117,56 @@ class PaymentCollectionsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create, update, or delete a list of payment sessions of a Payment Collections. If a payment session is not provided in the `sessions` array, it's deleted. + * @param {string} id - The ID of the payment collection. + * @param {StorePostPaymentCollectionsBatchSessionsReq} payload - The attributes of each session to update. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * To add two new payment sessions: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * + * // Total amount = 10000 + * medusa.paymentCollections.managePaymentSessionsBatch(paymentId, { + * sessions: [ + * { + * provider_id: "stripe", + * amount: 5000, + * }, + * { + * provider_id: "manual", + * amount: 5000, + * }, + * ] + * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }) + * ``` + * + * To update a payment session and another one by not including it in the payload: + * + * ```ts + * medusa.paymentCollections.managePaymentSessionsBatch(paymentId, { + * sessions: [ + * { + * provider_id: "stripe", + * amount: 10000, + * session_id: "ps_123456" + * }, + * ] + * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }) + * ``` + */ managePaymentSessionsBatch( id: string, payload: StorePostPaymentCollectionsBatchSessionsReq, @@ -53,6 +176,22 @@ class PaymentCollectionsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Create a Payment Session for a payment provider in a Payment Collection. + * @param {string} id - The ID of the payment collection. + * @param {StorePaymentCollectionSessionsReq} payload - The payment session to create. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the payment collection's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.paymentCollections.managePaymentSession(payment_id, { provider_id: "stripe" }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id); + * }) + */ managePaymentSession( id: string, payload: StorePaymentCollectionSessionsReq, @@ -62,6 +201,21 @@ class PaymentCollectionsResource extends BaseResource { return this.client.request("POST", path, payload, {}, customHeaders) } + /** + * Refresh a Payment Session's data to ensure that it is in sync with the Payment Collection. + * @param {string} id - The ID of the payment collection. + * @param {string} session_id - The ID of the payment session. + * @param customHeaders + * @returns {ResponsePromise} Resolves to the refreshed payment session's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId) + * .then(({ payment_session }) => { + * console.log(payment_session.id); + * }) + */ refreshPaymentSession( id: string, session_id: string, diff --git a/packages/medusa-js/src/resources/payment-methods.ts b/packages/medusa-js/src/resources/payment-methods.ts index e0bb199ec0..0af972903c 100644 --- a/packages/medusa-js/src/resources/payment-methods.ts +++ b/packages/medusa-js/src/resources/payment-methods.ts @@ -2,12 +2,27 @@ import { StoreCustomersListPaymentMethodsRes } from "@medusajs/medusa" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to Payment Method API Routes part of the [Store Customer API Routes](https://docs.medusajs.com/api/store#customers_postcustomers). All its method + * are available in the JS Client under the `medusa.customers.paymentMethods` property. + * + * All methods in this class require {@link AuthResource.authenticate | customer authentication}. + */ class PaymentMethodsResource extends BaseResource { /** - * Lists customer payment methods - * @param {string} id id of cart - * @param customHeaders - * @return {StoreCustomersListPaymentMethodsRes} + * Retrieve the logged-in customer's saved payment methods. This method only works with payment providers created with the deprecated Payment Service interface. + * The payment methods are saved using the Payment Service's third-party service, and not on the Medusa backend. So, they're retrieved from the third-party service. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {StoreCustomersListPaymentMethodsRes} Resolves to the customer's payment methods. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged + * medusa.customers.paymentMethods.list() + * .then(({ payment_methods }) => { + * console.log(payment_methods.length); + * }) */ list( customHeaders: Record = {} diff --git a/packages/medusa-js/src/resources/product-categories.ts b/packages/medusa-js/src/resources/product-categories.ts index 7362278f58..d09cfbe0a9 100644 --- a/packages/medusa-js/src/resources/product-categories.ts +++ b/packages/medusa-js/src/resources/product-categories.ts @@ -8,13 +8,51 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Product Category API Routes](https://docs.medusajs.com/api/store#product-categories_getproductcategories). All its method + * are available in the JS Client under the `medusa.productCategories` property. + * + * Products can be categoriezed into categories. A product can be associated more than one category. + * Using the methods in this class, you can list or retrieve a category's details and products. + * + * Related Guide: [How to use product categories in a storefront](https://docs.medusajs.com/modules/products/storefront/use-categories). + * + * @featureFlag product_categories + */ class ProductCategoriesResource extends BaseResource { /** - * @description Retrieves a single product category - * @param {string} id - id of the product category - * @param {string} query is optional. Can contain a fields or relations for the returned list - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Product Category's details. + * @param {string} id - The ID of the product category. + * @param {StoreGetProductCategoriesCategoryParams} query - Configurations to apply on the retrieved product categories. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product category's details. + * + * @example + * A simple example that retrieves a product category by its ID: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.productCategories.retrieve(productCategoryId) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) + * ``` + * + * To specify relations that should be retrieved: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.productCategories.retrieve(productCategoryId, { + * expand: "products" + * }) + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) + * ``` */ retrieve( id: string, @@ -32,10 +70,67 @@ class ProductCategoriesResource extends BaseResource { } /** - * @description Retrieves a list of product categories - * @param {string} query is optional. Can contain a limit and offset for the returned list - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of product categories. The product categories can be filtered by fields such as `handle` or `q` passed in the `query` parameter. + * The product categories can also be paginated. This method can also be used to retrieve a product category by its handle. + * @param {StoreGetProductCategoriesParams} query - Filters and pagination configurations to apply on the retrieved product categories. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product categories with pagination fields. + * + * @example + * To list product categories: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.productCategories.list() + * .then(({ product_categories, limit, offset, count }) => { + * console.log(product_categories.length); + * }) + * ``` + * + * To retrieve a product category by its handle: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.productCategories.list({ + * handle: "women", + * }) + * .then(({ product_categories, limit, offset, count }) => { + * if (!product_categories.length) { + * // category does not exist + * } + * const category = product_categories[0] + * }) + * ``` + * + * To specify relations that should be retrieved within the product categories: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.productCategories.list({ + * expand: "products" + * }) + * .then(({ product_categories, limit, offset, count }) => { + * console.log(product_categories.length); + * }) + * ``` + * + * By default, only the first `100` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.productCategories.list({ + * expand: "products", + * limit, + * offset + * }) + * .then(({ product_categories, limit, offset, count }) => { + * console.log(product_categories.length); + * }) + * ``` */ list( query?: StoreGetProductCategoriesParams, diff --git a/packages/medusa-js/src/resources/product-tags.ts b/packages/medusa-js/src/resources/product-tags.ts index 68a58ffa64..7b9fde8a5f 100644 --- a/packages/medusa-js/src/resources/product-tags.ts +++ b/packages/medusa-js/src/resources/product-tags.ts @@ -6,12 +6,45 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Product Tag API Routes](https://docs.medusajs.com/api/store#product-tags). All its method + * are available in the JS Client under the `medusa.productTags` property. + * + * Product tags are string values that can be used to filter products by. + * Products can have more than one tag, and products can share tags. + */ class ProductTagsResource extends BaseResource { /** - * @description Retrieves a list of product tags - * @param {StoreGetProductTagsParams} query is optional. Can contain a limit and offset for the returned list - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of product tags. The product tags can be filtered by fields such as `id` or `q` passed in the `query` parameter. The product tags can also be sorted or paginated. + * @param {StoreGetProductTagsParams} query - Filters and pagination configurations to apply on the retrieved product tags. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product tags with pagination fields. + * + * @example + * To list product tags: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.productTags.list() + * .then(({ product_tags }) => { + * console.log(product_tags.length); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.productTags.list({ + * limit, + * offset + * }) + * .then(({ product_tags }) => { + * console.log(product_tags.length); + * }) + * ``` */ list( query?: StoreGetProductTagsParams, diff --git a/packages/medusa-js/src/resources/product-types.ts b/packages/medusa-js/src/resources/product-types.ts index 9370e25d4c..aab30f9e5e 100644 --- a/packages/medusa-js/src/resources/product-types.ts +++ b/packages/medusa-js/src/resources/product-types.ts @@ -6,12 +6,47 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Product Type API Routes](https://docs.medusajs.com/api/store#product-types). All its method + * are available in the JS Client under the `medusa.productTypes` property. + * + * Product types are string values that can be used to filter products by. + * Products can have more than one tag, and products can share types. + */ class ProductTypesResource extends BaseResource { /** - * @description Retrieves a list of product types - * @param {StoreGetProductTypesParams} query is optional. Can contain a limit and offset for the returned list - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of product types. The product types can be filtered by fields such as `value` or `q` passed in the `query` parameter. The product types can also be sorted or paginated. + * @param {StoreGetProductTypesParams} query - Filters and pagination configurations to apply on retrieved product types. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product types with pagination fields. + * + * @example + * To list product types: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.productTypes.list() + * .then(({ product_types }) => { + * console.log(product_types.length); + * }) + * ``` + * + * By default, only the first `20` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.productTypes.list({ + * limit, + * offset + * }) + * .then(({ product_types }) => { + * console.log(product_types.length); + * }) + * ``` */ list( query?: StoreGetProductTypesParams, diff --git a/packages/medusa-js/src/resources/product-variants.ts b/packages/medusa-js/src/resources/product-variants.ts index 2f55473f5d..373cc46509 100644 --- a/packages/medusa-js/src/resources/product-variants.ts +++ b/packages/medusa-js/src/resources/product-variants.ts @@ -7,12 +7,31 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Product Variant API Routes](https://docs.medusajs.com/api/store#product-variants). All its method + * are available in the JS Client under the `medusa.product.variants` property. + * + * Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product. + */ class ProductVariantsResource extends BaseResource { /** - * @description Retrieves a single product variant - * @param {string} id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Product Variant's details. For accurate and correct pricing of the product variant based on the customer's context, it's highly recommended to pass fields such as + * `region_id`, `currency_code`, and `cart_id` when available. + * + * Passing `sales_channel_id` ensures retrieving only variants of products available in the current sales channel. + * You can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`. + * @param {string} id - The ID of the product variant. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product variant's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.product.variants.retrieve(productVariantId) + * .then(({ variant }) => { + * console.log(variant.id); + * }) */ retrieve(id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/variants/${id}` @@ -20,10 +39,59 @@ class ProductVariantsResource extends BaseResource { } /** - * @description Retrieves a list of of Product Variants - * @param {StoreGetVariantsParams} query - * @param customHeaders - * @return {ResponsePromise} + * Retrieves a list of product variants. The product variants can be filtered by fields such as `id` or `title` passed in the `query` parameter. The product variants can also be paginated. + * + * For accurate and correct pricing of the product variants based on the customer's context, it's highly recommended to pass fields such as + * `region_id`, `currency_code`, and `cart_id` when available. + * + * Passing `sales_channel_id` ensures retrieving only variants of products available in the specified sales channel. + * You can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`. + * @param {StoreGetVariantsParams} query - Filters and pagination configurations applied on the retrieved product variants. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of product variants. + * + * @example + * To list product variants: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.product.variants.list() + * .then(({ variants }) => { + * console.log(variants.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the product variants: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.product.variants.list({ + * expand: "product" + * }) + * .then(({ variants }) => { + * console.log(variants.length); + * }) + * ``` + * + * By default, only the first `100` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.product.variants.list({ + * expand: "product", + * limit, + * offset + * }) + * .then(({ variants }) => { + * console.log(variants.length); + * }) + * ``` */ list(query?: StoreGetVariantsParams, customHeaders: Record = {}): ResponsePromise { let path = `/store/variants` diff --git a/packages/medusa-js/src/resources/products.ts b/packages/medusa-js/src/resources/products.ts index b40052806c..d8f6a6f597 100644 --- a/packages/medusa-js/src/resources/products.ts +++ b/packages/medusa-js/src/resources/products.ts @@ -10,14 +10,38 @@ import { ResponsePromise } from "../typings" import BaseResource from "./base" import ProductVariantsResource from "./product-variants" +/** + * This class is used to send requests to [Store Product API Routes](https://docs.medusajs.com/api/store#products). All its method + * are available in the JS Client under the `medusa.products` property. + * + * Products are saleable items in a store. This also includes [saleable gift cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards) in a store. + * Using the methods in this class, you can filter products by categories, collections, sales channels, and more. + * + * Related Guide: [How to show products in a storefront](https://docs.medusajs.com/modules/products/storefront/show-products). + */ class ProductsResource extends BaseResource { + /** + * An instance of {@link ProductVariantsResource} used to send requests to [Store Product Variant API Routes](https://docs.medusajs.com/api/store#product-variants_getvariants). + */ public variants = new ProductVariantsResource(this.client) /** - * @description Retrieves a single Product - * @param {string} id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Product's details. For accurate and correct pricing of the product based on the customer's context, it's highly recommended to pass fields such as + * `region_id`, `currency_code`, and `cart_id` when available. + * + * Passing `sales_channel_id` ensures retrieving only products available in the current sales channel. + * You can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`. + * @param {string} id - The product's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the product's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.products.retrieve(productId) + * .then(({ product }) => { + * console.log(product.id); + * }) */ retrieve( id: string, @@ -28,10 +52,21 @@ class ProductsResource extends BaseResource { } /** - * @description Searches for products - * @param {StorePostSearchReq} searchOptions is required - * @param customHeaders - * @return {ResponsePromise} + * Run a search query on products using the search service installed on the Medusa backend. The searching is handled through the search service, so the returned data's + * format depends on the search service you're using. + * @param {StorePostSearchReq} searchOptions - Fields to search products. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of search results. The format of the items depends on the search engine installed on the Medusa backend. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.products.search({ + * q: "Shirt" + * }) + * .then(({ hits }) => { + * console.log(hits.length); + * }) */ search( searchOptions: StorePostSearchReq, @@ -42,10 +77,57 @@ class ProductsResource extends BaseResource { } /** - * @description Retrieves a list of products - * @param {StoreGetProductsParams} query is optional. Can contain a limit and offset for the returned list - * @param customHeaders - * @return {ResponsePromise} + * Retrieves a list of products. The products can be filtered by fields such as `id` or `q` passed in the `query` parameter. The products can also be sorted or paginated. + * This method can also be used to retrieve a product by its handle. + * + * For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as + * `region_id`, `currency_code`, and `cart_id` when available. + * + * Passing `sales_channel_id` ensures retrieving only products available in the specified sales channel. + * You can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`. + * @param {StoreGetProductsParams} query - Filters and pagination configurations to apply on the retrieved products. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of products with pagination fields. + * + * @example + * To list products: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.products.list() + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + * + * To specify relations that should be retrieved within the products: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.products.list({ + * expand: "variants" + * }) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` + * + * By default, only the first `100` records are retrieved. You can control pagination by specifying the `limit` and `offset` properties: + * + * ```ts + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.products.list({ + * expand: "variants", + * limit, + * offset + * }) + * .then(({ products, limit, offset, count }) => { + * console.log(products.length); + * }) + * ``` */ list( query?: StoreGetProductsParams, diff --git a/packages/medusa-js/src/resources/regions.ts b/packages/medusa-js/src/resources/regions.ts index dceaa7afb3..06e73914ad 100644 --- a/packages/medusa-js/src/resources/regions.ts +++ b/packages/medusa-js/src/resources/regions.ts @@ -2,11 +2,28 @@ import { ResponsePromise } from "../typings" import { StoreRegionsListRes, StoreRegionsRes } from "@medusajs/medusa" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Region API Routes](https://docs.medusajs.com/api/store#regions_getregions). All its method + * are available in the JS Client under the `medusa.regions` property. + * + * Regions are different countries or geographical regions that the commerce store serves customers in. + * Customers can choose what region they're in, which can be used to change the prices shown based on the region and its currency. + * + * Related Guide: [How to use regions in a storefront](https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions) + */ class RegionsResource extends BaseResource { /** - * @description Retrieves a list of regions - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of regions. This method is useful to show the customer all available regions to choose from. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of regions with pagination fields. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.regions.list() + * .then(({ regions, count, limit, offset }) => { + * console.log(regions.length); + * }) */ list(customHeaders: Record = {}): ResponsePromise { const path = `/store/regions` @@ -14,10 +31,18 @@ class RegionsResource extends BaseResource { } /** - * @description Retrieves a region - * @param {string} id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Region's details. + * @param {string} id - The region's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the region's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.regions.retrieve(regionId) + * .then(({ region }) => { + * console.log(region.id); + * }) */ retrieve(id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/regions/${id}` diff --git a/packages/medusa-js/src/resources/return-reasons.ts b/packages/medusa-js/src/resources/return-reasons.ts index 7011329cab..5e61ef157c 100644 --- a/packages/medusa-js/src/resources/return-reasons.ts +++ b/packages/medusa-js/src/resources/return-reasons.ts @@ -5,12 +5,26 @@ import { } from "@medusajs/medusa" import { ResponsePromise } from "../typings" +/** + * This class is used to send requests to [Store Return Reason API Routes](https://docs.medusajs.com/api/store#return-reasons). All its method + * are available in the JS Client under the `medusa.returnReasons` property. + * + * Return reasons are key-value pairs that are used to specify why an order return is being created. + */ class ReturnReasonsResource extends BaseResource { /** - * @description Retrieves a single Return Reason - * @param {string} id is required - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Return Reason's details. + * @param {string} id - The ID of the return reason. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the return reason's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.returnReasons.retrieve(reasonId) + * .then(({ return_reason }) => { + * console.log(return_reason.id); + * }) */ retrieve(id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/return-reasons/${id}` @@ -18,9 +32,17 @@ class ReturnReasonsResource extends BaseResource { } /** - * Lists return reasons defined in Medusa Admin - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of Return Reasons. This is useful when implementing a Create Return flow in the storefront. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of return reasons. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.returnReasons.list() + * .then(({ return_reasons }) => { + * console.log(return_reasons.length); + * }) */ list(customHeaders: Record = {}): ResponsePromise { const path = `/store/return-reasons` diff --git a/packages/medusa-js/src/resources/returns.ts b/packages/medusa-js/src/resources/returns.ts index 17b6358191..cbd4a05db9 100644 --- a/packages/medusa-js/src/resources/returns.ts +++ b/packages/medusa-js/src/resources/returns.ts @@ -2,12 +2,36 @@ import BaseResource from "./base" import { ResponsePromise } from "../typings" import { StoreReturnsRes, StorePostReturnsReq } from "@medusajs/medusa" +/** + * This class is used to send requests to [Store Return API Routes](https://docs.medusajs.com/api/store#returns). All its method + * are available in the JS Client under the `medusa.returns` property. + * + * A return can be created by a customer to return items in an order. + * + * Related Guide: [How to create a return in a storefront](https://docs.medusajs.com/modules/orders/storefront/create-return). + */ class ReturnsResource extends BaseResource { /** - * Creates a return request - * @param {StorePostReturnsReq} payload details needed to create a return - * @param customHeaders - * @return {ResponsePromise} + * Create a return for an order. If a return shipping method is specified, the return is automatically fulfilled. + * @param {StorePostReturnsReq} payload - The data of the return to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the return's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.returns.create({ + * order_id, + * items: [ + * { + * item_id, + * quantity: 1 + * } + * ] + * }) + * .then((data) => { + * console.log(data.return.id); + * }) */ create(payload: StorePostReturnsReq, customHeaders: Record = {}): ResponsePromise { const path = `/store/returns` diff --git a/packages/medusa-js/src/resources/shipping-options.ts b/packages/medusa-js/src/resources/shipping-options.ts index 280f1479de..d3d6631db9 100644 --- a/packages/medusa-js/src/resources/shipping-options.ts +++ b/packages/medusa-js/src/resources/shipping-options.ts @@ -6,12 +6,28 @@ import qs from "qs" import { ResponsePromise } from "../typings" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Shipping Option API Routes](https://docs.medusajs.com/api/store#shipping-options). All its method + * are available in the JS Client under the `medusa.shippingOptions` property. + * + * A shipping option is used to define the available shipping methods during checkout or when creating a return. + * + * Related Guide: [Shipping Option architecture](https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option). + */ class ShippingOptionsResource extends BaseResource { /** - * @description Lists shipping options available for a cart - * @param {string} cart_id - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of shipping options available for a cart. + * @param {string} cart_id - The cart's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of shipping options. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.shippingOptions.listCartOptions(cartId) + * .then(({ shipping_options }) => { + * console.log(shipping_options.length); + * }) */ listCartOptions(cart_id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/shipping-options/${cart_id}` @@ -19,10 +35,18 @@ class ShippingOptionsResource extends BaseResource { } /** - * @description Lists shipping options available - * @param {StoreGetShippingOptionsParams} query - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a list of shipping options. The shipping options can be filtered using the `query` parameter. + * @param {StoreGetShippingOptionsParams} query - The filters to apply on the shipping options. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the list of shipping options. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.shippingOptions.list() + * .then(({ shipping_options }) => { + * console.log(shipping_options.length); + * }) */ list( query?: StoreGetShippingOptionsParams, diff --git a/packages/medusa-js/src/resources/swaps.ts b/packages/medusa-js/src/resources/swaps.ts index f35fc15634..a6a140a101 100644 --- a/packages/medusa-js/src/resources/swaps.ts +++ b/packages/medusa-js/src/resources/swaps.ts @@ -2,12 +2,48 @@ import { ResponsePromise } from "../typings" import { StoreSwapsRes, StorePostSwapsReq } from "@medusajs/medusa" import BaseResource from "./base" +/** + * This class is used to send requests to [Store Swap API Routes](https://docs.medusajs.com/api/store#swaps). All its method + * are available in the JS Client under the `medusa.swaps` property. + * + * A swap is created by a customer or an admin to exchange an item with a new one. + * Creating a swap implicitely includes creating a return for the item being exchanged. + * + * Related Guide: [How to create a swap in a storefront](https://docs.medusajs.com/modules/orders/storefront/create-swap) + */ class SwapsResource extends BaseResource { /** - * @description Creates a swap from a cart - * @param {StorePostSwapsReq} payload - * @param customHeaders - * @return {ResponsePromise} + * Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled. + * To complete the swap, you must use the {@link CartsResource.complete} method passing it the ID of the swap's cart. + * + * An idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to + * the response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency + * key in the `Idempotency-Key` header. + * @param {StorePostSwapsReq} payload - The data of the swap to be created. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the swap's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.swaps.create({ + * order_id, + * return_items: [ + * { + * item_id, + * quantity: 1 + * } + * ], + * additional_items: [ + * { + * variant_id, + * quantity: 1 + * } + * ] + * }) + * .then(({ swap }) => { + * console.log(swap.id); + * }) */ create(payload: StorePostSwapsReq, customHeaders: Record = {}): ResponsePromise { const path = `/store/swaps` @@ -15,10 +51,18 @@ class SwapsResource extends BaseResource { } /** - * @description Retrieves a swap by cart id - * @param {string} cart_id id of cart - * @param customHeaders - * @return {ResponsePromise} + * Retrieve a Swap's details by the ID of its cart. + * @param {string} cart_id - The cart's ID. + * @param {Record} customHeaders - Custom headers to attach to the request. + * @returns {ResponsePromise} Resolves to the swap's details. + * + * @example + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.swaps.retrieveByCartId(cartId) + * .then(({ swap }) => { + * console.log(swap.id); + * }) */ retrieveByCartId(cart_id: string, customHeaders: Record = {}): ResponsePromise { const path = `/store/swaps/${cart_id}` diff --git a/packages/medusa-react/src/hooks/admin/publishable-api-keys/queries.ts b/packages/medusa-react/src/hooks/admin/publishable-api-keys/queries.ts index 83a6f117a6..bcc521dd39 100644 --- a/packages/medusa-react/src/hooks/admin/publishable-api-keys/queries.ts +++ b/packages/medusa-react/src/hooks/admin/publishable-api-keys/queries.ts @@ -1,7 +1,7 @@ import { AdminPublishableApiKeysListRes, + AdminPublishableApiKeysListSalesChannelsRes, AdminPublishableApiKeysRes, - AdminSalesChannelsListRes, GetPublishableApiKeySalesChannelsParams, GetPublishableApiKeysParams, } from "@medusajs/medusa" @@ -67,7 +67,7 @@ export const useAdminPublishableApiKeySalesChannels = ( id: string, query?: GetPublishableApiKeySalesChannelsParams, options?: UseQueryOptionsWrapper< - Response, + Response, Error, ReturnType > diff --git a/packages/medusa/oas/admin.oas.base.yaml b/packages/medusa/oas/admin.oas.base.yaml index 5020a9636f..a107fecfb2 100644 --- a/packages/medusa/oas/admin.oas.base.yaml +++ b/packages/medusa/oas/admin.oas.base.yaml @@ -20,7 +20,7 @@ tags: - name: Batch Jobs description: | A batch job is a task that is performed by the Medusa backend asynchronusly. For example, the Import Product feature is implemented using batch jobs. - Batch Job API Routes allows admins to manage the batch jobs and their state. + Batch Job API Routes allow admins to manage the batch jobs and their state. externalDocs: description: How to import products url: https://docs.medusajs.com/modules/products/admin/import-products @@ -194,7 +194,7 @@ tags: A shipping profile is used to group products that can be shipped in the same manner. They are created by the admin and they're not associated with a fulfillment provider. externalDocs: - description: Shipping Option architecture + description: Shipping Profile architecture url: https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile - name: Stock Locations description: | diff --git a/packages/medusa/oas/store.oas.base.yaml b/packages/medusa/oas/store.oas.base.yaml index 39a2a44b47..fa2ab873f3 100644 --- a/packages/medusa/oas/store.oas.base.yaml +++ b/packages/medusa/oas/store.oas.base.yaml @@ -8,8 +8,8 @@ info: tags: - name: Auth description: | - Authentication API Routes allow customers to manage their session, such as login or log out. - When a customer is logged in, the cookie header is set indicating the customer's login session. + Authentication API Routes allow you to manage a customer's session, such as login or log out. + You can send authenticated requests for a customer either using the Cookie header or using the JWT Token. externalDocs: description: How to implement customer profiles in your storefront url: https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles diff --git a/packages/medusa/src/api/routes/admin/auth/create-session.ts b/packages/medusa/src/api/routes/admin/auth/create-session.ts index 3d13e4d9e1..64d5b8283c 100644 --- a/packages/medusa/src/api/routes/admin/auth/create-session.ts +++ b/packages/medusa/src/api/routes/admin/auth/create-session.ts @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ user }) => { * console.log(user.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/auth/get-session.ts b/packages/medusa/src/api/routes/admin/auth/get-session.ts index 6f50299418..3bddd0beb3 100644 --- a/packages/medusa/src/api/routes/admin/auth/get-session.ts +++ b/packages/medusa/src/api/routes/admin/auth/get-session.ts @@ -19,7 +19,7 @@ import _ from "lodash" * medusa.admin.auth.getSession() * .then(({ user }) => { * console.log(user.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/auth/get-token.ts b/packages/medusa/src/api/routes/admin/auth/get-token.ts index f53381a4d1..dcdf74ecf5 100644 --- a/packages/medusa/src/api/routes/admin/auth/get-token.ts +++ b/packages/medusa/src/api/routes/admin/auth/get-token.ts @@ -30,7 +30,7 @@ import { AdminPostAuthReq } from "./create-session" * }) * .then(({ access_token }) => { * console.log(access_token); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/auth/index.ts b/packages/medusa/src/api/routes/admin/auth/index.ts index 7aa5b49fa3..cdbb646c14 100644 --- a/packages/medusa/src/api/routes/admin/auth/index.ts +++ b/packages/medusa/src/api/routes/admin/auth/index.ts @@ -29,6 +29,7 @@ export default (app) => { /** * @schema AdminAuthRes * type: object + * description: "The user's details." * required: * - user * properties: @@ -43,6 +44,7 @@ export type AdminAuthRes = { /** * @schema AdminBearerAuthRes * type: object + * description: "The access token of the user, if they're authenticated successfully." * properties: * access_token: * description: Access token that can be used to send authenticated requests. diff --git a/packages/medusa/src/api/routes/admin/batch/cancel-batch-job.ts b/packages/medusa/src/api/routes/admin/batch/cancel-batch-job.ts index b1176e02e7..dd99c00b5d 100644 --- a/packages/medusa/src/api/routes/admin/batch/cancel-batch-job.ts +++ b/packages/medusa/src/api/routes/admin/batch/cancel-batch-job.ts @@ -21,7 +21,7 @@ import { EntityManager } from "typeorm" * medusa.admin.batchJobs.cancel(batchJobId) * .then(({ batch_job }) => { * console.log(batch_job.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts b/packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts index 19610b2681..40ee349680 100644 --- a/packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts +++ b/packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts @@ -21,7 +21,7 @@ import { EntityManager } from "typeorm" * medusa.admin.batchJobs.confirm(batchJobId) * .then(({ batch_job }) => { * console.log(batch_job.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/batch/create-batch-job.ts b/packages/medusa/src/api/routes/admin/batch/create-batch-job.ts index 69ebc3201c..a73376cb70 100644 --- a/packages/medusa/src/api/routes/admin/batch/create-batch-job.ts +++ b/packages/medusa/src/api/routes/admin/batch/create-batch-job.ts @@ -35,7 +35,7 @@ import { validator } from "../../../../utils/validator" * dry_run: false * }).then((({ batch_job }) => { * console.log(batch_job.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -102,7 +102,8 @@ export default async (req, res) => { * properties: * type: * type: string - * description: The type of batch job to start, which is defined by the `batchType` property of the associated batch job strategy. + * description: >- + * The type of batch job to start, which is defined by the `batchType` property of the associated batch job strategy. * example: product-export * context: * type: object diff --git a/packages/medusa/src/api/routes/admin/batch/get-batch-job.ts b/packages/medusa/src/api/routes/admin/batch/get-batch-job.ts index 78fea59f38..32cd46e916 100644 --- a/packages/medusa/src/api/routes/admin/batch/get-batch-job.ts +++ b/packages/medusa/src/api/routes/admin/batch/get-batch-job.ts @@ -18,7 +18,7 @@ * medusa.admin.batchJobs.retrieve(batchJobId) * .then(({ batch_job }) => { * console.log(batch_job.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/batch/index.ts b/packages/medusa/src/api/routes/admin/batch/index.ts index 5e4b53b362..3eb78dc27e 100644 --- a/packages/medusa/src/api/routes/admin/batch/index.ts +++ b/packages/medusa/src/api/routes/admin/batch/index.ts @@ -45,6 +45,7 @@ export default (app) => { /** * @schema AdminBatchJobRes * type: object + * description: "The batch job's details." * required: * - batch_job * properties: diff --git a/packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts b/packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts index 6f683913d0..711d395ffb 100644 --- a/packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts +++ b/packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts @@ -276,40 +276,70 @@ export default async (req: Request, res) => { }) } +/** + * Request parameters used to configure and paginate retrieved batch jobs. + */ export class AdminGetBatchPaginationParams { + /** + * {@inheritDoc FindPaginationParams.limit} + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 10 + /** + * {@inheritDoc FindPaginationParams.offset} + */ @IsNumber() @IsOptional() @Type(() => Number) offset = 0 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string + /** + * {@inheritDoc FindParams.fields} + */ @IsString() @IsOptional() fields?: string + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string } +/** + * Parameters used to filter and configure pagination of the retrieved batch jobs. + */ export class AdminGetBatchParams extends AdminGetBatchPaginationParams { + /** + * IDs to filter batch jobs by. + */ @IsOptional() @IsArray() @IsType([String, [String]]) id?: string | string[] + /** + * Types to filter batch jobs by. + */ @IsArray() @IsOptional() type?: string[] + /** + * Date filters to apply on the batch jobs' `confirmed_at` date. + */ @IsOptional() @Transform(({ value }) => { return value === "null" ? null : value @@ -317,6 +347,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams { @Type(() => DateComparisonOperator) confirmed_at?: DateComparisonOperator | null + /** + * Date filters to apply on the batch jobs' `pre_processed_at` date. + */ @IsOptional() @Transform(({ value }) => { return value === "null" ? null : value @@ -324,6 +357,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams { @Type(() => DateComparisonOperator) pre_processed_at?: DateComparisonOperator | null + /** + * Date filters to apply on the batch jobs' `completed_at` date. + */ @IsOptional() @Transform(({ value }) => { return value === "null" ? null : value @@ -331,6 +367,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams { @Type(() => DateComparisonOperator) completed_at?: DateComparisonOperator | null + /** + * Date filters to apply on the batch jobs' `failed_at` date. + */ @IsOptional() @Transform(({ value }) => { return value === "null" ? null : value @@ -338,6 +377,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams { @Type(() => DateComparisonOperator) failed_at?: DateComparisonOperator | null + /** + * Date filters to apply on the batch jobs' `canceled_at` date. + */ @IsOptional() @Transform(({ value }) => { return value === "null" ? null : value @@ -345,10 +387,16 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams { @Type(() => DateComparisonOperator) canceled_at?: DateComparisonOperator | null + /** + * Date filters to apply on the batch jobs' `created_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() created_at?: DateComparisonOperator + /** + * Date filters to apply on the batch jobs' `updated_at` date. + */ @IsOptional() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator diff --git a/packages/medusa/src/api/routes/admin/collections/create-collection.ts b/packages/medusa/src/api/routes/admin/collections/create-collection.ts index 6ad92724f3..9e0d625dca 100644 --- a/packages/medusa/src/api/routes/admin/collections/create-collection.ts +++ b/packages/medusa/src/api/routes/admin/collections/create-collection.ts @@ -29,7 +29,7 @@ import { defaultAdminCollectionsRelations } from "." * }) * .then(({ collection }) => { * console.log(collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/collections/delete-collection.ts b/packages/medusa/src/api/routes/admin/collections/delete-collection.ts index 8b9b94f1f5..a237090bb8 100644 --- a/packages/medusa/src/api/routes/admin/collections/delete-collection.ts +++ b/packages/medusa/src/api/routes/admin/collections/delete-collection.ts @@ -23,7 +23,7 @@ import ProductCollectionService from "../../../../services/product-collection" * medusa.admin.collections.delete(collectionId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/collections/get-collection.ts b/packages/medusa/src/api/routes/admin/collections/get-collection.ts index 337c1d39d9..c5ed909ea8 100644 --- a/packages/medusa/src/api/routes/admin/collections/get-collection.ts +++ b/packages/medusa/src/api/routes/admin/collections/get-collection.ts @@ -23,7 +23,7 @@ import { defaultAdminCollectionsRelations } from "." * medusa.admin.collections.retrieve(collectionId) * .then(({ collection }) => { * console.log(collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/collections/index.ts b/packages/medusa/src/api/routes/admin/collections/index.ts index a621c03e00..7e280f57b1 100644 --- a/packages/medusa/src/api/routes/admin/collections/index.ts +++ b/packages/medusa/src/api/routes/admin/collections/index.ts @@ -122,6 +122,7 @@ export type AdminCollectionsDeleteRes = DeleteResponse /** * @schema AdminDeleteProductsFromCollectionRes * type: object + * description: "Deletion operation details" * required: * - id * - object @@ -150,6 +151,7 @@ export type AdminDeleteProductsFromCollectionRes = { /** * @schema AdminCollectionsRes * type: object + * description: The collection's details. * x-expanded-relations: * field: collection * relations: @@ -158,7 +160,7 @@ export type AdminDeleteProductsFromCollectionRes = { * - collection * properties: * collection: - * type: "Product Collection details." + * description: "Product Collection details." * $ref: "#/components/schemas/ProductCollection" */ export type AdminCollectionsRes = { diff --git a/packages/medusa/src/api/routes/admin/collections/list-collections.ts b/packages/medusa/src/api/routes/admin/collections/list-collections.ts index cc589d03bd..c7dc3b4ba4 100644 --- a/packages/medusa/src/api/routes/admin/collections/list-collections.ts +++ b/packages/medusa/src/api/routes/admin/collections/list-collections.ts @@ -97,7 +97,7 @@ import { Type } from "class-transformer" * medusa.admin.collections.list() * .then(({ collections, limit, offset, count }) => { * console.log(collections.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -150,47 +150,80 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to configure the pagination of the retrieved product collections. + */ export class AdminGetCollectionsPaginationParams { + /** + * {@inheritDoc FindPaginationParams.limit} + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 10 + /** + * {@inheritDoc FindPaginationParams.offset} + */ @IsNumber() @IsOptional() @Type(() => Number) offset = 0 } +/** + * Parameters used to filter and configure the pagination of the retrieved product collections. + */ // eslint-disable-next-line max-len export class AdminGetCollectionsParams extends AdminGetCollectionsPaginationParams { + /** + * Title to filter product collections by. + */ @IsOptional() @IsString() title?: string + /** + * Handle to filter product collections by. + */ @IsOptional() @IsString() handle?: string + /** + * Date filters to apply on the product collections' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the product collections' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the product collections' `deleted_at` date. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) deleted_at?: DateComparisonOperator + /** + * Term to search product collections by their title and handle. + */ @IsString() @IsOptional() q?: string + /** + * Filter product collections by their associated discount condition's ID. + */ @IsString() @IsOptional() discount_condition_id?: string diff --git a/packages/medusa/src/api/routes/admin/collections/update-collection.ts b/packages/medusa/src/api/routes/admin/collections/update-collection.ts index 0d96b118b8..410aa1657b 100644 --- a/packages/medusa/src/api/routes/admin/collections/update-collection.ts +++ b/packages/medusa/src/api/routes/admin/collections/update-collection.ts @@ -31,7 +31,7 @@ import { defaultAdminCollectionsRelations } from "." * }) * .then(({ collection }) => { * console.log(collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/currencies/index.ts b/packages/medusa/src/api/routes/admin/currencies/index.ts index 6586bfeb18..dbf37b3c55 100644 --- a/packages/medusa/src/api/routes/admin/currencies/index.ts +++ b/packages/medusa/src/api/routes/admin/currencies/index.ts @@ -35,6 +35,7 @@ export default (app) => { /** * @schema AdminCurrenciesListRes * type: object + * description: List of currencies with pagination fields. * required: * - currencies * - count @@ -63,6 +64,7 @@ export type AdminCurrenciesListRes = PaginatedResponse & { /** * @schema AdminCurrenciesRes * type: object + * description: A currency's details. * required: * - currency * properties: diff --git a/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts b/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts index 7df6930886..32682192c1 100644 --- a/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts +++ b/packages/medusa/src/api/routes/admin/currencies/list-currencies.ts @@ -36,7 +36,7 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators * medusa.admin.currencies.list() * .then(({ currencies, count, offset, limit }) => { * console.log(currencies.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -78,17 +78,32 @@ export default async (req: ExtendedRequest, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved currencies. + */ export class AdminGetCurrenciesParams extends FindPaginationParams { + /** + * Code to filter currencies by. + */ @IsString() @IsOptional() code?: string + /** + * Filter currencies by whether they include tax. + * + * @featureFlag tax_inclusive_pricing + */ @FeatureFlagDecorators(TaxInclusivePricingFeatureFlag.key, [ IsBoolean(), IsOptional(), ]) includes_tax?: boolean + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + * By default, the returned currencies will be sorted by their `created_at` field. + */ @IsString() @IsOptional() order?: string diff --git a/packages/medusa/src/api/routes/admin/currencies/update-currency.ts b/packages/medusa/src/api/routes/admin/currencies/update-currency.ts index 28ee7d87ba..c5c953fe8e 100644 --- a/packages/medusa/src/api/routes/admin/currencies/update-currency.ts +++ b/packages/medusa/src/api/routes/admin/currencies/update-currency.ts @@ -33,7 +33,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ currency }) => { * console.log(currency.code); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts b/packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts index 0a27b4cb8c..dd18f2322a 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts @@ -38,7 +38,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer_group }) => { * console.log(customer_group.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customer-groups/create-customer-group.ts b/packages/medusa/src/api/routes/admin/customer-groups/create-customer-group.ts index 0e92266bd8..0052abcc0d 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/create-customer-group.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/create-customer-group.ts @@ -9,7 +9,7 @@ import { validator } from "../../../../utils/validator" * @oas [post] /admin/customer-groups * operationId: "PostCustomerGroups" * summary: "Create a Customer Group" - * description: "Creates a Customer Group." + * description: "Create a Customer Group." * x-authenticated: true * requestBody: * content: @@ -30,7 +30,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer_group }) => { * console.log(customer_group.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customer-groups/delete-customer-group.ts b/packages/medusa/src/api/routes/admin/customer-groups/delete-customer-group.ts index 994a4c6e03..1d8d47c67e 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/delete-customer-group.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/delete-customer-group.ts @@ -23,7 +23,7 @@ import { EntityManager } from "typeorm" * medusa.admin.customerGroups.delete(customerGroupId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts b/packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts index daf3c51806..e421f84a82 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts @@ -38,7 +38,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer_group }) => { * console.log(customer_group.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group-customers.ts b/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group-customers.ts index d6e2a4dc33..692fd351b5 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group-customers.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group-customers.ts @@ -29,7 +29,7 @@ import { Type } from "class-transformer" * medusa.admin.customerGroups.listCustomers(customerGroupId) * .then(({ customers }) => { * console.log(customers.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -75,23 +75,38 @@ export default async (req: Request, res: Response) => { res.json(result) } +/** + * Parameters used to filter and configure the pagination of the retrieved customer group's customers. + */ // eslint-disable-next-line max-len export class AdminGetGroupsGroupCustomersParams { + /** + * Search term to search customers by their email, first name, and last name. + */ @IsString() @IsOptional() q?: string + /** + * {@inheritDoc FindPaginationParams.limit} + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + */ @IsOptional() @IsNumber() @IsOptional() @Type(() => Number) offset = 0 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string diff --git a/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group.ts b/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group.ts index 1429faa16a..8875735796 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/get-customer-group.ts @@ -26,7 +26,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.customerGroups.retrieve(customerGroupId) * .then(({ customer_group }) => { * console.log(customer_group.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customer-groups/index.ts b/packages/medusa/src/api/routes/admin/customer-groups/index.ts index c807230f65..b32eaef819 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/index.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/index.ts @@ -59,6 +59,7 @@ export default (app) => { /** * @schema AdminCustomerGroupsRes * type: object + * description: "The customer group's details." * required: * - customer_group * properties: diff --git a/packages/medusa/src/api/routes/admin/customer-groups/list-customer-groups.ts b/packages/medusa/src/api/routes/admin/customer-groups/list-customer-groups.ts index 3111a660cf..be978f2170 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/list-customer-groups.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/list-customer-groups.ts @@ -113,7 +113,7 @@ import { Type } from "class-transformer" * medusa.admin.customerGroups.list() * .then(({ customer_groups, limit, offset, count }) => { * console.log(customer_groups.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -164,21 +164,36 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved customer groups. + */ export class AdminGetCustomerGroupsParams extends FilterableCustomerGroupProps { + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string + /** + * {@inheritDoc FindPaginationParams.offset} + */ @IsNumber() @IsOptional() @Type(() => Number) offset?: number = 0 + /** + * {@inheritDoc FindPaginationParams.limit} + */ @IsNumber() @IsOptional() @Type(() => Number) limit?: number = 10 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string diff --git a/packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts b/packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts index 7493bdf17b..b947ac4007 100644 --- a/packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts +++ b/packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts @@ -34,7 +34,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer_group }) => { * console.log(customer_group.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customers/create-customer.ts b/packages/medusa/src/api/routes/admin/customers/create-customer.ts index 52053cac2e..af5832b36d 100644 --- a/packages/medusa/src/api/routes/admin/customers/create-customer.ts +++ b/packages/medusa/src/api/routes/admin/customers/create-customer.ts @@ -8,7 +8,7 @@ import { EntityManager } from "typeorm" * @oas [post] /admin/customers * operationId: "PostCustomers" * summary: "Create a Customer" - * description: "Allow admins to create a customer." + * description: "Create a customer as an admin." * x-authenticated: true * requestBody: * content: @@ -32,7 +32,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customers/get-customer.ts b/packages/medusa/src/api/routes/admin/customers/get-customer.ts index d468a70c4c..32f88994f4 100644 --- a/packages/medusa/src/api/routes/admin/customers/get-customer.ts +++ b/packages/medusa/src/api/routes/admin/customers/get-customer.ts @@ -25,7 +25,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.customers.retrieve(customerId) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/customers/index.ts b/packages/medusa/src/api/routes/admin/customers/index.ts index e60193440d..f32fa5b9e7 100644 --- a/packages/medusa/src/api/routes/admin/customers/index.ts +++ b/packages/medusa/src/api/routes/admin/customers/index.ts @@ -23,6 +23,7 @@ export default (app) => { /** * @schema AdminCustomersRes * type: object + * description: "The customer's details." * x-expanded-relations: * field: customer * relations: @@ -41,6 +42,7 @@ export type AdminCustomersRes = { /** * @schema AdminCustomersListRes + * description: The list of customers with pagination fields. * type: object * required: * - customers diff --git a/packages/medusa/src/api/routes/admin/customers/list-customers.ts b/packages/medusa/src/api/routes/admin/customers/list-customers.ts index fb954719dd..3d90ee7643 100644 --- a/packages/medusa/src/api/routes/admin/customers/list-customers.ts +++ b/packages/medusa/src/api/routes/admin/customers/list-customers.ts @@ -37,7 +37,7 @@ import customerController from "../../../../controllers/customers" * medusa.admin.customers.list() * .then(({ customers, limit, offset, count }) => { * console.log(customers.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -79,18 +79,32 @@ export default async (req, res) => { res.json(result) } +/** + * Parameters used to filter and configure the pagination of the retrieved customers. + */ export class AdminGetCustomersParams extends AdminListCustomerSelector { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsNumber() @IsOptional() @Type(() => Number) offset = 0 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string diff --git a/packages/medusa/src/api/routes/admin/customers/update-customer.ts b/packages/medusa/src/api/routes/admin/customers/update-customer.ts index 874952dc1c..a7b69c0e0b 100644 --- a/packages/medusa/src/api/routes/admin/customers/update-customer.ts +++ b/packages/medusa/src/api/routes/admin/customers/update-customer.ts @@ -44,7 +44,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/add-region.ts b/packages/medusa/src/api/routes/admin/discounts/add-region.ts index 8e770e9de4..b0978c2f4b 100644 --- a/packages/medusa/src/api/routes/admin/discounts/add-region.ts +++ b/packages/medusa/src/api/routes/admin/discounts/add-region.ts @@ -25,7 +25,7 @@ import { EntityManager } from "typeorm" * medusa.admin.discounts.addRegion(discountId, regionId) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts b/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts index 9a2d72fbe1..eacffd6089 100644 --- a/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts +++ b/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts @@ -41,7 +41,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -128,7 +128,7 @@ export default async (req: Request, res: Response) => { * - id * properties: * id: - * description: The id of the item + * description: The ID of the item * type: string */ export class AdminPostDiscountsDiscountConditionsConditionBatchReq { diff --git a/packages/medusa/src/api/routes/admin/discounts/create-condition.ts b/packages/medusa/src/api/routes/admin/discounts/create-condition.ts index 9c6c6db694..c362c4fb5b 100644 --- a/packages/medusa/src/api/routes/admin/discounts/create-condition.ts +++ b/packages/medusa/src/api/routes/admin/discounts/create-condition.ts @@ -36,11 +36,12 @@ import { FindParams } from "../../../../types/common" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.discounts.createCondition(discountId, { - * operator: DiscountConditionOperator.IN + * operator: DiscountConditionOperator.IN, + * products: [productId] * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -107,8 +108,9 @@ export default async (req: Request, res: Response) => { * - operator * properties: * operator: - * description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that - * discountable resources are everything but the specified resources." + * description: >- + * Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that + * discountable resources are everything but the specified resources. * type: string * enum: [in, not_in] * products: diff --git a/packages/medusa/src/api/routes/admin/discounts/create-discount.ts b/packages/medusa/src/api/routes/admin/discounts/create-discount.ts index c889fe86ec..ad322d610e 100644 --- a/packages/medusa/src/api/routes/admin/discounts/create-discount.ts +++ b/packages/medusa/src/api/routes/admin/discounts/create-discount.ts @@ -63,7 +63,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -152,14 +152,16 @@ export default async (req: Request, res: Response) => { * description: "A short description of the discount" * type: * type: string - * description: "The type of the discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers." + * description: >- + * The type of the discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers. * enum: [fixed, percentage, free_shipping] * value: * type: number * description: "The value that the discount represents. This will depend on the type of the discount." * allocation: * type: string - * description: "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart." + * description: >- + * The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart. * enum: [total, item] * conditions: * type: array @@ -171,8 +173,9 @@ export default async (req: Request, res: Response) => { * properties: * operator: * type: string - * description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that - * discountable resources are everything but the specified resources." + * description: >- + * Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that + * discountable resources are everything but the specified resources. * enum: [in, not_in] * products: * type: array @@ -201,7 +204,8 @@ export default async (req: Request, res: Response) => { * type: string * is_disabled: * type: boolean - * description: Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers. + * description: >- + * Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers. * default: false * starts_at: * type: string @@ -277,24 +281,42 @@ export class AdminPostDiscountsReq { metadata?: Record } +/** + * Details of the discount rule to create. + */ export class AdminPostDiscountsDiscountRule { + /** + * The discount rule's description. + */ @IsString() @IsOptional() description?: string + /** + * The discount rule's type. + */ @IsEnum(DiscountRuleType, { message: `Invalid rule type, must be one of "fixed", "percentage" or "free_shipping"`, }) type: DiscountRuleType + /** + * The discount rule's value. + */ @IsNumber() value: number + /** + * The discount rule's allocation. + */ @IsEnum(AllocationType, { message: `Invalid allocation type, must be one of "total" or "item"`, }) allocation: AllocationType + /** + * The discount rule's conditions. + */ @IsOptional() @IsArray() @ValidateNested({ each: true }) @@ -302,9 +324,18 @@ export class AdminPostDiscountsDiscountRule { conditions?: AdminCreateCondition[] } +/** + * Details of the discount condition to create. + */ export class AdminCreateCondition extends AdminUpsertConditionsReq { + /** + * The operator of the discount condition. + */ @IsString() operator: DiscountConditionOperator } +/** + * {@inheritDoc FindParams} + */ export class AdminPostDiscountsParams extends FindParams {} diff --git a/packages/medusa/src/api/routes/admin/discounts/create-dynamic-code.ts b/packages/medusa/src/api/routes/admin/discounts/create-dynamic-code.ts index efef78e2f2..4c3f83573f 100644 --- a/packages/medusa/src/api/routes/admin/discounts/create-dynamic-code.ts +++ b/packages/medusa/src/api/routes/admin/discounts/create-dynamic-code.ts @@ -39,7 +39,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/delete-condition.ts b/packages/medusa/src/api/routes/admin/discounts/delete-condition.ts index 1e50df2c2f..2831f9d09a 100644 --- a/packages/medusa/src/api/routes/admin/discounts/delete-condition.ts +++ b/packages/medusa/src/api/routes/admin/discounts/delete-condition.ts @@ -8,7 +8,7 @@ import { FindParams } from "../../../../types/common" * @oas [delete] /admin/discounts/{discount_id}/conditions/{condition_id} * operationId: "DeleteDiscountsDiscountConditionsCondition" * summary: "Delete a Condition" - * description: "Deletes a Discount Condition. This does not delete resources associated to the discount condition." + * description: "Delete a Discount Condition. This does not delete resources associated to the discount condition." * x-authenticated: true * parameters: * - (path) discount_id=* {string} The ID of the Discount @@ -28,7 +28,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.discounts.deleteCondition(discountId, conditionId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/delete-discount.ts b/packages/medusa/src/api/routes/admin/discounts/delete-discount.ts index 9f4af47d89..2d504d1460 100644 --- a/packages/medusa/src/api/routes/admin/discounts/delete-discount.ts +++ b/packages/medusa/src/api/routes/admin/discounts/delete-discount.ts @@ -21,7 +21,7 @@ import { EntityManager } from "typeorm" * medusa.admin.discounts.delete(discountId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts b/packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts index 8b7666662d..5b8abd14f4 100644 --- a/packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts +++ b/packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts @@ -24,7 +24,7 @@ import { EntityManager } from "typeorm" * medusa.admin.discounts.deleteDynamicCode(discountId, code) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts b/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts index c67277d536..47db14ca18 100644 --- a/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts +++ b/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts @@ -12,7 +12,7 @@ import { FindParams } from "../../../../types/common" * @oas [delete] /admin/discounts/{discount_id}/conditions/{condition_id}/batch * operationId: "DeleteDiscountsDiscountConditionsConditionBatch" * summary: "Remove Batch Resources" - * description: "Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, but not the resource itself." + * description: "Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, not the resource itself." * x-authenticated: true * parameters: * - (path) discount_id=* {string} The ID of the discount. @@ -38,7 +38,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -110,12 +110,16 @@ export default async (req: Request, res: Response) => { res.status(200).json({ discount }) } +/** + * {@inheritDoc FindParams} + */ // eslint-disable-next-line max-len export class AdminDeleteDiscountsDiscountConditionsConditionBatchParams extends FindParams {} /** * @schema AdminDeleteDiscountsDiscountConditionsConditionBatchReq * type: object + * description: "The resources to remove." * required: * - resources * properties: diff --git a/packages/medusa/src/api/routes/admin/discounts/get-condition.ts b/packages/medusa/src/api/routes/admin/discounts/get-condition.ts index 5a0cc59b69..f1c5518e5b 100644 --- a/packages/medusa/src/api/routes/admin/discounts/get-condition.ts +++ b/packages/medusa/src/api/routes/admin/discounts/get-condition.ts @@ -26,7 +26,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.discounts.getCondition(discountId, conditionId) * .then(({ discount_condition }) => { * console.log(discount_condition.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts b/packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts index 217a0a2471..9596c8f3db 100644 --- a/packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts +++ b/packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts @@ -25,7 +25,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.discounts.retrieveByCode(code) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/get-discount.ts b/packages/medusa/src/api/routes/admin/discounts/get-discount.ts index 32b1847921..06e66cce20 100644 --- a/packages/medusa/src/api/routes/admin/discounts/get-discount.ts +++ b/packages/medusa/src/api/routes/admin/discounts/get-discount.ts @@ -6,7 +6,7 @@ import { FindParams } from "../../../../types/common" * @oas [get] /admin/discounts/{id} * operationId: "GetDiscountsDiscount" * summary: "Get a Discount" - * description: "Retrieves a Discount" + * description: "Retrieve a Discount." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Discount @@ -25,7 +25,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.discounts.retrieve(discountId) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/index.ts b/packages/medusa/src/api/routes/admin/discounts/index.ts index 8db5893ce4..26a3f40f8b 100644 --- a/packages/medusa/src/api/routes/admin/discounts/index.ts +++ b/packages/medusa/src/api/routes/admin/discounts/index.ts @@ -222,6 +222,7 @@ export const defaultAdminDiscountConditionRelations = ["discount_rule"] /** * @schema AdminDiscountsRes * type: object + * description: "The discount's details." * x-expanded-relations: * field: discount * relations: @@ -314,6 +315,7 @@ export type AdminDiscountConditionsDeleteRes = DeleteResponse & { /** * @schema AdminDiscountsListRes * type: object + * description: The list of discounts with pagination fields. * x-expanded-relations: * field: discounts * relations: @@ -329,6 +331,7 @@ export type AdminDiscountConditionsDeleteRes = DeleteResponse & { * properties: * discounts: * type: array + * description: "The list of discounts." * items: * $ref: "#/components/schemas/Discount" * count: diff --git a/packages/medusa/src/api/routes/admin/discounts/list-discounts.ts b/packages/medusa/src/api/routes/admin/discounts/list-discounts.ts index 4941062231..3f44bfab6e 100644 --- a/packages/medusa/src/api/routes/admin/discounts/list-discounts.ts +++ b/packages/medusa/src/api/routes/admin/discounts/list-discounts.ts @@ -52,7 +52,7 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean" * medusa.admin.discounts.list() * .then(({ discounts, limit, offset, count }) => { * console.log(discounts.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -103,24 +103,39 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved discounts. + */ export class AdminGetDiscountsParams extends extendedFindParamsMixin({ limit: 20, offset: 0, }) { + /** + * Filter discounts by their associated rule. + */ @ValidateNested() @IsOptional() @Type(() => AdminGetDiscountsDiscountRuleParams) rule?: AdminGetDiscountsDiscountRuleParams + /** + * Search terms to search discounts' code fields. + */ @IsString() @IsOptional() q?: string + /** + * Filter discounts by whether they're dynamic. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value)) is_dynamic?: boolean + /** + * Filter discounts by whether they're disabled. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value)) diff --git a/packages/medusa/src/api/routes/admin/discounts/remove-region.ts b/packages/medusa/src/api/routes/admin/discounts/remove-region.ts index 7f826bf31b..3d0f2391e7 100644 --- a/packages/medusa/src/api/routes/admin/discounts/remove-region.ts +++ b/packages/medusa/src/api/routes/admin/discounts/remove-region.ts @@ -24,7 +24,7 @@ import { EntityManager } from "typeorm" * medusa.admin.discounts.removeRegion(discountId, regionId) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/update-condition.ts b/packages/medusa/src/api/routes/admin/discounts/update-condition.ts index 25c4fafc73..bbe2fd13c6 100644 --- a/packages/medusa/src/api/routes/admin/discounts/update-condition.ts +++ b/packages/medusa/src/api/routes/admin/discounts/update-condition.ts @@ -39,7 +39,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/discounts/update-discount.ts b/packages/medusa/src/api/routes/admin/discounts/update-discount.ts index 65f79bdd06..3ee56e5c9a 100644 --- a/packages/medusa/src/api/routes/admin/discounts/update-discount.ts +++ b/packages/medusa/src/api/routes/admin/discounts/update-discount.ts @@ -52,7 +52,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ discount }) => { * console.log(discount.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -132,7 +132,8 @@ export default async (req: Request, res: Response) => { * description: "The value that the discount represents. This will depend on the type of the discount." * allocation: * type: string - * description: "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart." + * description: >- + * The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart. * enum: [total, item] * conditions: * type: array @@ -147,8 +148,9 @@ export default async (req: Request, res: Response) => { * description: "The ID of the condition" * operator: * type: string - * description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that - * discountable resources are everything but the specified resources." + * description: >- + * Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that + * discountable resources are everything but the specified resources. * enum: [in, not_in] * products: * type: array @@ -177,7 +179,8 @@ export default async (req: Request, res: Response) => { * type: string * is_disabled: * type: boolean - * description: Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers. + * description: >- + * Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers. * starts_at: * type: string * format: date-time @@ -249,25 +252,43 @@ export class AdminPostDiscountsDiscountReq { metadata?: Record } +/** + * The attributes of the discount rule to update. + */ export class AdminUpdateDiscountRule { + /** + * The discount rule's ID. + */ @IsString() @IsNotEmpty() id: string + /** + * The discount rule's description. + */ @IsString() @IsOptional() description?: string + /** + * The discount rule's value. + */ @IsNumber() @IsOptional() value?: number + /** + * The discount rule's allocation. + */ @IsOptional() @IsEnum(AllocationType, { message: `Invalid allocation type, must be one of "total" or "item"`, }) allocation?: AllocationType + /** + * The discount rule's discount conditions. + */ @IsOptional() @IsArray() @ValidateNested({ each: true }) @@ -275,11 +296,20 @@ export class AdminUpdateDiscountRule { conditions?: AdminUpsertCondition[] } +/** + * The attributes to create or update in the discount condition. + */ export class AdminUpsertCondition extends AdminUpsertConditionsReq { + /** + * The discount condition's ID. + */ @IsString() @IsOptional() id?: string + /** + * The discount condition's operator. + */ @IsString() @IsOptional() operator: DiscountConditionOperator diff --git a/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts b/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts index 7a7e44f8a6..5409a2d192 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts @@ -63,7 +63,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ draft_order }) => { * console.log(draft_order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -173,7 +173,8 @@ enum Status { * - shipping_methods * properties: * status: - * description: "The status of the draft order. The draft order's default status is `open`. It's changed to `completed` when its payment is marked as paid." + * description: >- + * The status of the draft order. The draft order's default status is `open`. It's changed to `completed` when its payment is marked as paid. * type: string * enum: [open, completed] * email: diff --git a/packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts b/packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts index 958e11cba1..a52d35b5a4 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts @@ -48,7 +48,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ draft_order }) => { * console.log(draft_order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/draft-orders/delete-draft-order.ts b/packages/medusa/src/api/routes/admin/draft-orders/delete-draft-order.ts index 5695fb7d7a..a9b6e7b976 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/delete-draft-order.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/delete-draft-order.ts @@ -5,7 +5,7 @@ import { EntityManager } from "typeorm" * @oas [delete] /admin/draft-orders/{id} * operationId: DeleteDraftOrdersDraftOrder * summary: Delete a Draft Order - * description: "Delete a Draft Order" + * description: "Delete a Draft Order." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Draft Order. @@ -21,7 +21,7 @@ import { EntityManager } from "typeorm" * medusa.admin.draftOrders.delete(draftOrderId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/draft-orders/delete-line-item.ts b/packages/medusa/src/api/routes/admin/draft-orders/delete-line-item.ts index afeee9fa4e..52572965ca 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/delete-line-item.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/delete-line-item.ts @@ -14,7 +14,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [delete] /admin/draft-orders/{id}/line-items/{line_id} * operationId: DeleteDraftOrdersDraftOrderLineItemsItem * summary: Delete a Line Item - * description: "Deletes a Line Item from a Draft Order." + * description: "Delete a Line Item from a Draft Order." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Draft Order. @@ -31,7 +31,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.draftOrders.removeLineItem(draftOrderId, itemId) * .then(({ draft_order }) => { * console.log(draft_order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/draft-orders/get-draft-order.ts b/packages/medusa/src/api/routes/admin/draft-orders/get-draft-order.ts index 69f101cd30..9252f20d8b 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/get-draft-order.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/get-draft-order.ts @@ -29,7 +29,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.draftOrders.retrieve(draftOrderId) * .then(({ draft_order }) => { * console.log(draft_order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/draft-orders/index.ts b/packages/medusa/src/api/routes/admin/draft-orders/index.ts index 8b8fba4158..ebef7957fd 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/index.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/index.ts @@ -94,6 +94,7 @@ export const defaultAdminDraftOrdersFields: (keyof DraftOrder)[] = [ /** * @schema AdminPostDraftOrdersDraftOrderRegisterPaymentRes * type: object + * description: "The order's details." * required: * - order * properties: @@ -107,6 +108,7 @@ export type AdminPostDraftOrdersDraftOrderRegisterPaymentRes = { /** * @schema AdminDraftOrdersRes * type: object + * description: "The list of draft orders." * x-expanded-relations: * field: draft_order * relations: @@ -201,6 +203,7 @@ export type AdminDraftOrdersDeleteRes = DeleteResponse /** * @schema AdminDraftOrdersListRes + * description: "The list of draft orders with pagination fields." * type: object * x-expanded-relations: * field: draft_orders diff --git a/packages/medusa/src/api/routes/admin/draft-orders/list-draft-orders.ts b/packages/medusa/src/api/routes/admin/draft-orders/list-draft-orders.ts index bc4bfbcc41..7b242b4f0f 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/list-draft-orders.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/list-draft-orders.ts @@ -34,7 +34,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.draftOrders.list() * .then(({ draft_orders, limit, offset, count }) => { * console.log(draft_orders.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -100,16 +100,28 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved draft orders. + */ export class AdminGetDraftOrdersParams { + /** + * Search term to search draft orders by their display IDs and emails. + */ @IsString() @IsOptional() q?: string + /** + * {@inheritDoc FindPaginationParams.limit} + */ @IsNumber() @IsOptional() @Type(() => Number) limit?: number = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + */ @IsNumber() @IsOptional() @Type(() => Number) diff --git a/packages/medusa/src/api/routes/admin/draft-orders/register-payment.ts b/packages/medusa/src/api/routes/admin/draft-orders/register-payment.ts index 9f0b7dc538..3d0445fcc2 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/register-payment.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/register-payment.ts @@ -37,7 +37,7 @@ import { promiseAll } from "@medusajs/utils" * medusa.admin.draftOrders.markPaid(draftOrderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts b/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts index 50b15c8de8..323e63fd3e 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts @@ -48,7 +48,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ draft_order }) => { * console.log(draft_order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts b/packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts index 98a9b8be14..d085533800 100644 --- a/packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts +++ b/packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts @@ -17,7 +17,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/draft-orders/{id}/line-items/{line_id} * operationId: "PostDraftOrdersDraftOrderLineItemsItem" * summary: "Update a Line Item" - * description: "Update a Line Item in a Draft Order" + * description: "Update a Line Item in a Draft Order." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Draft Order. @@ -41,7 +41,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ draft_order }) => { * console.log(draft_order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts b/packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts index a0a3b63371..805fe2bc75 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts +++ b/packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts @@ -30,7 +30,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ gift_card }) => { * console.log(gift_card.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -98,7 +98,8 @@ export default async (req, res) => { * description: The value (excluding VAT) that the Gift Card should represent. * is_disabled: * type: boolean - * description: Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers. + * description: >- + * Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers. * ends_at: * type: string * format: date-time diff --git a/packages/medusa/src/api/routes/admin/gift-cards/delete-gift-card.ts b/packages/medusa/src/api/routes/admin/gift-cards/delete-gift-card.ts index 7604816dde..f596145dce 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/delete-gift-card.ts +++ b/packages/medusa/src/api/routes/admin/gift-cards/delete-gift-card.ts @@ -20,7 +20,7 @@ import { EntityManager } from "typeorm" * medusa.admin.giftCards.delete(giftCardId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/gift-cards/get-gift-card.ts b/packages/medusa/src/api/routes/admin/gift-cards/get-gift-card.ts index c27babc6aa..540c8d6eaf 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/get-gift-card.ts +++ b/packages/medusa/src/api/routes/admin/gift-cards/get-gift-card.ts @@ -20,7 +20,7 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./" * medusa.admin.giftCards.retrieve(giftCardId) * .then(({ gift_card }) => { * console.log(gift_card.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/gift-cards/index.ts b/packages/medusa/src/api/routes/admin/gift-cards/index.ts index ad8b203128..ef9da8a05d 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/index.ts +++ b/packages/medusa/src/api/routes/admin/gift-cards/index.ts @@ -59,6 +59,7 @@ export const defaultAdminGiftCardRelations = ["region", "order"] /** * @schema AdminGiftCardsRes * type: object + * description: "The gift card's details." * x-expanded-relations: * field: gift_card * relations: @@ -103,6 +104,7 @@ export type AdminGiftCardsDeleteRes = DeleteResponse /** * @schema AdminGiftCardsListRes * type: object + * description: "The list of gift cards with pagination fields." * x-expanded-relations: * field: gift_cards * relations: @@ -119,6 +121,7 @@ export type AdminGiftCardsDeleteRes = DeleteResponse * properties: * gift_cards: * type: array + * description: "The list of gift cards." * items: * $ref: "#/components/schemas/GiftCard" * count: diff --git a/packages/medusa/src/api/routes/admin/gift-cards/list-gift-cards.ts b/packages/medusa/src/api/routes/admin/gift-cards/list-gift-cards.ts index 4dd9fbfe19..77e6f1ebb0 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/list-gift-cards.ts +++ b/packages/medusa/src/api/routes/admin/gift-cards/list-gift-cards.ts @@ -29,7 +29,7 @@ import { isDefined } from "medusa-core-utils" * medusa.admin.giftCards.list() * .then(({ gift_cards, limit, offset, count }) => { * console.log(gift_cards.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -79,17 +79,31 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved gift cards. + */ export class AdminGetGiftCardsParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsOptional() @IsInt() @Type(() => Number) limit = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsInt() @Type(() => Number) offset = 0 + /** + * Search term to search gift cards by their code and display ID. + */ @IsOptional() @IsString() q?: string diff --git a/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts b/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts index e367c47181..f85a949ffc 100644 --- a/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts +++ b/packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ gift_card }) => { * console.log(gift_card.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -100,7 +100,8 @@ export default async (req, res) => { * description: The value (excluding VAT) that the Gift Card should represent. * is_disabled: * type: boolean - * description: Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers. + * description: >- + * Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers. * ends_at: * type: string * format: date-time diff --git a/packages/medusa/src/api/routes/admin/inventory-items/create-inventory-item.ts b/packages/medusa/src/api/routes/admin/inventory-items/create-inventory-item.ts index 4b64df33a1..c5991e2e54 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/create-inventory-item.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/create-inventory-item.ts @@ -39,7 +39,7 @@ import { MedusaError } from "@medusajs/utils" * }) * .then(({ inventory_item }) => { * console.log(inventory_item.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -158,7 +158,7 @@ function generateAttachInventoryToVariantHandler( productVariantInventoryService: ProductVariantInventoryService ) { return async ({ data }) => { - let inventoryItems = await productVariantInventoryService.listByVariant( + const inventoryItems = await productVariantInventoryService.listByVariant( variantId ) @@ -235,6 +235,15 @@ function generateAttachInventoryToVariantHandler( * material: * description: The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers. * type: string + * title: + * description: The inventory item's title. + * type: string + * description: + * description: The inventory item's description. + * type: string + * thumbnail: + * description: The inventory item's thumbnail. + * type: string * metadata: * description: An optional set of key-value pairs with additional information. * type: object diff --git a/packages/medusa/src/api/routes/admin/inventory-items/create-location-level.ts b/packages/medusa/src/api/routes/admin/inventory-items/create-location-level.ts index 5f67bb216b..e76fbb85c3 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/create-location-level.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/create-location-level.ts @@ -6,8 +6,8 @@ import { FindParams } from "../../../../types/common" /** * @oas [post] /admin/inventory-items/{id}/location-levels * operationId: "PostInventoryItemsInventoryItemLocationLevels" - * summary: "Create an Location Level" - * description: "Create an Location Level for a given Inventory Item." + * summary: "Create a Location Level" + * description: "Create a Location Level for a given Inventory Item." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Inventory Item. @@ -34,7 +34,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ inventory_item }) => { * console.log(inventory_item.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/inventory-items/delete-inventory-item.ts b/packages/medusa/src/api/routes/admin/inventory-items/delete-inventory-item.ts index d82ee63e21..4558f2cc6b 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/delete-inventory-item.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/delete-inventory-item.ts @@ -21,9 +21,9 @@ import { ProductVariantInventoryService } from "../../../../services" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.inventoryItems.delete(inventoryItemId) - * .then(({ id, object, deleted }) => { - * console.log(id) - * }) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/inventory-items/delete-location-level.ts b/packages/medusa/src/api/routes/admin/inventory-items/delete-location-level.ts index 3c7c5be7a7..572cc3341b 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/delete-location-level.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/delete-location-level.ts @@ -24,7 +24,7 @@ import { EntityManager } from "typeorm" * medusa.admin.inventoryItems.deleteLocationLevel(inventoryItemId, locationId) * .then(({ inventory_item }) => { * console.log(inventory_item.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/inventory-items/get-inventory-item.ts b/packages/medusa/src/api/routes/admin/inventory-items/get-inventory-item.ts index 20490580e9..e18dcf7bc1 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/get-inventory-item.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/get-inventory-item.ts @@ -26,7 +26,7 @@ import { joinLevels } from "./utils/join-levels" * medusa.admin.inventoryItems.retrieve(inventoryItemId) * .then(({ inventory_item }) => { * console.log(inventory_item.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/inventory-items/index.ts b/packages/medusa/src/api/routes/admin/inventory-items/index.ts index af07827739..ab69044d77 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/index.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/index.ts @@ -166,6 +166,7 @@ export const defaultAdminInventoryItemRelations = [] /** * @schema AdminInventoryItemsRes * type: object + * description: The inventory item's details. * required: * - inventory_item * properties: @@ -293,17 +294,20 @@ export type AdminInventoryItemsListWithVariantsAndLocationLevelsRes = /** * @schema AdminInventoryItemsLocationLevelsRes * type: object + * description: "Details of inventory items and their associated location levels." * required: * - inventory_item * properties: * inventory_item: * type: object + * description: "An inventory item's ID and associated location levels." * required: * - id * - location_levels * properties: * id: * description: The id of the location + * type: string * location_levels: * description: List of stock levels at a given location * type: array diff --git a/packages/medusa/src/api/routes/admin/inventory-items/list-inventory-items.ts b/packages/medusa/src/api/routes/admin/inventory-items/list-inventory-items.ts index 8133e3c091..7b546d3a31 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/list-inventory-items.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/list-inventory-items.ts @@ -76,7 +76,7 @@ import { Transform } from "class-transformer" * medusa.admin.inventoryItems.list() * .then(({ inventory_items, count, offset, limit }) => { * console.log(inventory_items.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -150,58 +150,100 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved inventory items. + */ export class AdminGetInventoryItemsParams extends extendedFindParamsMixin({ limit: 20, offset: 0, }) { + /** + * IDs to filter inventory items by. + */ @IsOptional() @IsType([String, [String]]) id?: string | string[] + /** + * Search terms to search inventory items' sku, title, and description. + */ @IsOptional() @IsString() q?: string + /** + * Location IDs to filter inventory items by. + */ @IsOptional() @IsType([String, [String]]) location_id?: string | string[] + /** + * SKUs to filter inventory items by. + */ @IsOptional() @IsType([String, [String]]) sku?: string | string[] + /** + * Origin countries to filter inventory items by. + */ @IsOptional() @IsType([String, [String]]) origin_country?: string | string[] + /** + * MID codes to filter inventory items by. + */ @IsOptional() @IsType([String, [String]]) mid_code?: string | string[] + /** + * Materials to filter inventory items by. + */ @IsOptional() @IsType([String, [String]]) material?: string | string[] + /** + * String filters to apply to inventory items' `hs_code` field. + */ @IsOptional() @IsType([String, [String], StringComparisonOperator]) hs_code?: string | string[] | StringComparisonOperator + /** + * Number filters to apply to inventory items' `weight` field. + */ @IsOptional() @IsType([Number, NumericalComparisonOperator]) weight?: number | NumericalComparisonOperator + /** + * Number filters to apply to inventory items' `length` field. + */ @IsOptional() @IsType([Number, NumericalComparisonOperator]) length?: number | NumericalComparisonOperator + /** + * Number filters to apply to inventory items' `height` field. + */ @IsOptional() @IsType([Number, NumericalComparisonOperator]) height?: number | NumericalComparisonOperator + /** + * Number filters to apply to inventory items' `width` field. + */ @IsOptional() @IsType([Number, NumericalComparisonOperator]) width?: number | NumericalComparisonOperator + /** + * Filter inventory items by whether they require shipping. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => value === "true") diff --git a/packages/medusa/src/api/routes/admin/inventory-items/list-location-levels.ts b/packages/medusa/src/api/routes/admin/inventory-items/list-location-levels.ts index 3bcbfac142..9c919211ca 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/list-location-levels.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/list-location-levels.ts @@ -9,7 +9,7 @@ import { IsType } from "../../../../utils/validators/is-type" * @oas [get] /admin/inventory-items/{id}/location-levels * operationId: "GetInventoryItemsInventoryItemLocationLevels" * summary: "List Inventory Level" - * description: "Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`. The inventory levels can also be paginated." + * description: "Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Inventory Item the locations are associated with. @@ -37,7 +37,7 @@ import { IsType } from "../../../../utils/validators/is-type" * medusa.admin.inventoryItems.listLocationLevels(inventoryItemId) * .then(({ inventory_item }) => { * console.log(inventory_item.location_levels); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -94,6 +94,9 @@ export default async (req: Request, res: Response) => { // eslint-disable-next-line max-len export class AdminGetInventoryItemsItemLocationLevelsParams extends FindParams { + /** + * Location IDs to filter location levels. + */ @IsOptional() @IsString({ each: true }) location_id?: string[] diff --git a/packages/medusa/src/api/routes/admin/inventory-items/update-inventory-item.ts b/packages/medusa/src/api/routes/admin/inventory-items/update-inventory-item.ts index dd2c0c5ddc..6beff04636 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/update-inventory-item.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/update-inventory-item.ts @@ -35,7 +35,7 @@ import { IInventoryService } from "@medusajs/types" * }) * .then(({ inventory_item }) => { * console.log(inventory_item.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -94,6 +94,7 @@ export default async (req: Request, res: Response) => { /** * @schema AdminPostInventoryItemsInventoryItemReq * type: object + * description: "The attributes to update in an inventory item." * properties: * hs_code: * description: The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers. @@ -119,6 +120,15 @@ export default async (req: Request, res: Response) => { * length: * description: The length of the Inventory Item. May be used in shipping rate calculations. * type: number + * title: + * description: The inventory item's title. + * type: string + * description: + * description: The inventory item's description. + * type: string + * thumbnail: + * description: The inventory item's thumbnail. + * type: string * requires_shipping: * description: Whether the item requires shipping. * type: boolean diff --git a/packages/medusa/src/api/routes/admin/inventory-items/update-location-level.ts b/packages/medusa/src/api/routes/admin/inventory-items/update-location-level.ts index 81fbe6ce58..c150c6d699 100644 --- a/packages/medusa/src/api/routes/admin/inventory-items/update-location-level.ts +++ b/packages/medusa/src/api/routes/admin/inventory-items/update-location-level.ts @@ -35,7 +35,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ inventory_item }) => { * console.log(inventory_item.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/invites/accept-invite.ts b/packages/medusa/src/api/routes/admin/invites/accept-invite.ts index 50ffa4cc73..7651b8af49 100644 --- a/packages/medusa/src/api/routes/admin/invites/accept-invite.ts +++ b/packages/medusa/src/api/routes/admin/invites/accept-invite.ts @@ -43,7 +43,7 @@ import { EntityManager } from "typeorm" * }) * .catch(() => { * // an error occurred - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -95,15 +95,27 @@ export default async (req, res) => { res.sendStatus(200) } +/** + * Details of the use accepting the invite. + */ export class AdminPostInvitesInviteAcceptUserReq { + /** + * The invite's first name. + */ @IsString() @IsOptional() first_name: string + /** + * The invite's last name. + */ @IsString() @IsOptional() last_name: string + /** + * The invite's password + */ @IsString() password: string } @@ -111,6 +123,7 @@ export class AdminPostInvitesInviteAcceptUserReq { /** * @schema AdminPostInvitesInviteAcceptReq * type: object + * description: "The details of the invite to be accepted." * required: * - token * - user diff --git a/packages/medusa/src/api/routes/admin/invites/create-invite.ts b/packages/medusa/src/api/routes/admin/invites/create-invite.ts index b14408f072..ec21f7684b 100644 --- a/packages/medusa/src/api/routes/admin/invites/create-invite.ts +++ b/packages/medusa/src/api/routes/admin/invites/create-invite.ts @@ -35,7 +35,7 @@ import { EntityManager } from "typeorm" * }) * .catch(() => { * // an error occurred - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/invites/delete-invite.ts b/packages/medusa/src/api/routes/admin/invites/delete-invite.ts index 9348e65082..ea37448f0e 100644 --- a/packages/medusa/src/api/routes/admin/invites/delete-invite.ts +++ b/packages/medusa/src/api/routes/admin/invites/delete-invite.ts @@ -21,7 +21,7 @@ import InviteService from "../../../../services/invite" * medusa.admin.invites.delete(inviteId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/invites/index.ts b/packages/medusa/src/api/routes/admin/invites/index.ts index 1e641d131d..72a06d8985 100644 --- a/packages/medusa/src/api/routes/admin/invites/index.ts +++ b/packages/medusa/src/api/routes/admin/invites/index.ts @@ -56,6 +56,7 @@ export type AdminInviteDeleteRes = DeleteResponse /** * @schema AdminListInvitesRes + * description: "The list of invites." * type: object * required: * - invites diff --git a/packages/medusa/src/api/routes/admin/invites/list-invites.ts b/packages/medusa/src/api/routes/admin/invites/list-invites.ts index 47dc7c8f50..55b358f0e7 100644 --- a/packages/medusa/src/api/routes/admin/invites/list-invites.ts +++ b/packages/medusa/src/api/routes/admin/invites/list-invites.ts @@ -18,7 +18,7 @@ import InviteService from "../../../../services/invite" * medusa.admin.invites.list() * .then(({ invites }) => { * console.log(invites.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/invites/resend-invite.ts b/packages/medusa/src/api/routes/admin/invites/resend-invite.ts index d2919cf677..4a9d53130f 100644 --- a/packages/medusa/src/api/routes/admin/invites/resend-invite.ts +++ b/packages/medusa/src/api/routes/admin/invites/resend-invite.ts @@ -25,7 +25,7 @@ import { EntityManager } from "typeorm" * }) * .catch(() => { * // an error occurred - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/notes/create-note.ts b/packages/medusa/src/api/routes/admin/notes/create-note.ts index 89c66d3ca9..3ee5e01c61 100644 --- a/packages/medusa/src/api/routes/admin/notes/create-note.ts +++ b/packages/medusa/src/api/routes/admin/notes/create-note.ts @@ -31,7 +31,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ note }) => { * console.log(note.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/notes/delete-note.ts b/packages/medusa/src/api/routes/admin/notes/delete-note.ts index 6e83abd1ef..dc72e14a74 100644 --- a/packages/medusa/src/api/routes/admin/notes/delete-note.ts +++ b/packages/medusa/src/api/routes/admin/notes/delete-note.ts @@ -21,7 +21,7 @@ import NoteService from "../../../../services/note" * medusa.admin.notes.delete(noteId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/notes/get-note.ts b/packages/medusa/src/api/routes/admin/notes/get-note.ts index c487210591..e2e37b061a 100644 --- a/packages/medusa/src/api/routes/admin/notes/get-note.ts +++ b/packages/medusa/src/api/routes/admin/notes/get-note.ts @@ -20,7 +20,7 @@ import NoteService from "../../../../services/note" * medusa.admin.notes.retrieve(noteId) * .then(({ note }) => { * console.log(note.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/notes/index.ts b/packages/medusa/src/api/routes/admin/notes/index.ts index 8fce6ac2ae..83c928ed66 100644 --- a/packages/medusa/src/api/routes/admin/notes/index.ts +++ b/packages/medusa/src/api/routes/admin/notes/index.ts @@ -25,6 +25,7 @@ export default (app) => { /** * @schema AdminNotesRes * type: object + * description: "The note's details." * required: * - note * properties: @@ -61,6 +62,7 @@ export type AdminNotesDeleteRes = DeleteResponse /** * @schema AdminNotesListRes * type: object + * description: "The list of notes with pagination fields." * required: * - notes * - count diff --git a/packages/medusa/src/api/routes/admin/notes/list-notes.ts b/packages/medusa/src/api/routes/admin/notes/list-notes.ts index caeebe1f30..99588bac99 100644 --- a/packages/medusa/src/api/routes/admin/notes/list-notes.ts +++ b/packages/medusa/src/api/routes/admin/notes/list-notes.ts @@ -28,7 +28,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.notes.list() * .then(({ notes, limit, offset, count }) => { * console.log(notes.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -84,16 +84,30 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved notes. + */ export class AdminGetNotesParams { + /** + * Resource ID to filter notes by. + */ @IsString() @IsOptional() resource_id?: string + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) diff --git a/packages/medusa/src/api/routes/admin/notes/update-note.ts b/packages/medusa/src/api/routes/admin/notes/update-note.ts index 2949ac301e..c02c8adc64 100644 --- a/packages/medusa/src/api/routes/admin/notes/update-note.ts +++ b/packages/medusa/src/api/routes/admin/notes/update-note.ts @@ -8,7 +8,7 @@ import { EntityManager } from "typeorm" * operationId: "PostNotesNote" * summary: "Update a Note" * x-authenticated: true - * description: "Update a Note's details.'" + * description: "Update a Note's details." * parameters: * - (path) id=* {string} The ID of the Note * requestBody: @@ -30,7 +30,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ note }) => { * console.log(note.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/notifications/index.ts b/packages/medusa/src/api/routes/admin/notifications/index.ts index 4b17e3bea2..3e58d629c2 100644 --- a/packages/medusa/src/api/routes/admin/notifications/index.ts +++ b/packages/medusa/src/api/routes/admin/notifications/index.ts @@ -69,6 +69,7 @@ export type AdminNotificationsListRes = PaginatedResponse & { /** * @schema AdminNotificationsRes * type: object + * description: "The notification's details." * x-expanded-relations: * field: notification * relations: diff --git a/packages/medusa/src/api/routes/admin/notifications/list-notifications.ts b/packages/medusa/src/api/routes/admin/notifications/list-notifications.ts index 4ee8c8794a..3d58548af8 100644 --- a/packages/medusa/src/api/routes/admin/notifications/list-notifications.ts +++ b/packages/medusa/src/api/routes/admin/notifications/list-notifications.ts @@ -40,7 +40,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.notifications.list() * .then(({ notifications }) => { * console.log(notifications.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -150,41 +150,73 @@ export default async (req, res) => { res.json({ notifications: data, count, limit, offset }) } +/** + * Parameters used to filter and configure the pagination of the retrieved notifications. + */ export class AdminGetNotificationsParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsOptional() @IsInt() @Type(() => Number) limit?: number = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsInt() @Type(() => Number) offset?: number = 0 + /** + * {@inheritDoc FindParams.fields} + */ @IsOptional() @IsString() fields?: string + /** + * {@inheritDoc FindParams.expand} + */ @IsOptional() @IsString() expand?: string + /** + * Event name to filter notifications by. + */ @IsOptional() @IsString() event_name?: string + /** + * Resource type to filter notifications by. + */ @IsOptional() @IsString() resource_type?: string + /** + * Resource ID to filter notifications by. + */ @IsOptional() @IsString() resource_id?: string + /** + * Filter notifications by their `to` field. + */ @IsOptional() @IsString() to?: string + /** + * Whether to include resends in the results. + */ @IsOptional() @IsBooleanString() include_resends?: string diff --git a/packages/medusa/src/api/routes/admin/notifications/resend-notification.ts b/packages/medusa/src/api/routes/admin/notifications/resend-notification.ts index bdc9d419fa..341317bd4f 100644 --- a/packages/medusa/src/api/routes/admin/notifications/resend-notification.ts +++ b/packages/medusa/src/api/routes/admin/notifications/resend-notification.ts @@ -34,7 +34,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.notifications.resend(notificationId) * .then(({ notification }) => { * console.log(notification.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -104,7 +104,8 @@ export default async (req, res) => { * type: object * properties: * to: - * description: "A new address or user identifier that the Notification should be sent to. If not provided, the previous `to` field of the notification will be used." + * description: >- + * A new address or user identifier that the Notification should be sent to. If not provided, the previous `to` field of the notification will be used. * type: string */ export class AdminPostNotificationsNotificationResendReq { diff --git a/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts index 3828c9ff75..c7174754ac 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts @@ -10,7 +10,7 @@ import { * @oas [post] /admin/order-edits/{id}/cancel * operationId: "PostOrderEditsOrderEditCancel" * summary: "Cancel an Order Edit" - * description: "Cancel an OrderEdit." + * description: "Cancel an Order Edit." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the OrderEdit. @@ -24,9 +24,9 @@ import { * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.cancel(orderEditId) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts index 1fd3c12d22..fd9c959ed2 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts @@ -24,9 +24,9 @@ import { * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.confirm(orderEditId) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts index da702065cf..3b83180c6e 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts @@ -28,9 +28,9 @@ import { * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.create({ orderId }) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts index b3f7842ed9..365bc74fca 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts @@ -26,9 +26,9 @@ import { * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.removeLineItem(orderEditId, lineItemId) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts index e90d553783..182cd0f349 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts @@ -20,9 +20,9 @@ import { OrderEditService } from "../../../../services" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.deleteItemChange(orderEdit_id, itemChangeId) - * .then(({ id, object, deleted }) => { - * console.log(id) - * }) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts index 26fb3bd01a..60801ab779 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts @@ -19,9 +19,9 @@ import { OrderEditService } from "../../../../services" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.delete(orderEditId) - * .then(({ id, object, deleted }) => { - * console.log(id) - * }) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts index acb4b46cf4..c5a3149b59 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts @@ -23,9 +23,9 @@ import { FindParams } from "../../../../types/common" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.retrieve(orderEditId) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/index.ts b/packages/medusa/src/api/routes/admin/order-edits/index.ts index a834b6c509..be6ba64473 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/index.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/index.ts @@ -101,6 +101,7 @@ export default (app) => { /** * @schema AdminOrderEditsRes * type: object + * description: "The order edit details." * x-expanded-relations: * field: order_edit * relations: @@ -150,6 +151,7 @@ export type AdminOrderEditsRes = { /** * @schema AdminOrderEditsListRes * type: object + * description: "The list of order edits with pagination fields." * x-expanded-relations: * field: order_edits * relations: @@ -235,6 +237,7 @@ export type AdminOrderEditDeleteRes = DeleteResponse /** * @schema AdminOrderEditItemChangeDeleteRes * type: object + * description: "The details of deleting order edit item changes." * required: * - id * - object diff --git a/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts index 96c567dac5..5b77995742 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts @@ -27,9 +27,9 @@ import { IsOptional, IsString } from "class-validator" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.list() - * .then(({ order_edits, count, limit, offset }) => { - * console.log(order_edits.length) - * }) + * .then(({ order_edits, count, limit, offset }) => { + * console.log(order_edits.length) + * }) * - lang: Shell * label: cURL * source: | @@ -85,14 +85,23 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved order edits. + */ export class GetOrderEditsParams extends extendedFindParamsMixin({ limit: 20, offset: 0, }) { + /** + * Search term to search order edits by their internal note. + */ @IsString() @IsOptional() q?: string + /** + * Filter the order edits by their associated order's ID. + */ @IsString() @IsOptional() order_id?: string diff --git a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts index 219f6a7300..04a0bec0db 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts @@ -30,9 +30,9 @@ import { * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.requestConfirmation(orderEditId) - * .then({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts index 4171061957..5b2388bb52 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts @@ -32,11 +32,11 @@ import { * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.orderEdits.updateLineItem(orderEditId, lineItemId, { - * quantity: 5 - * }) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * quantity: 5 + * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts index bbb50f2683..257a21cf51 100644 --- a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts +++ b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts @@ -12,7 +12,7 @@ import { * @oas [post] /admin/order-edits/{id} * operationId: "PostOrderEditsOrderEdit" * summary: "Update an Order Edit" - * description: "Updates an Order Edit's details." + * description: "Update an Order Edit's details." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the OrderEdit. @@ -33,9 +33,9 @@ import { * medusa.admin.orderEdits.update(orderEditId, { * internal_note: "internal reason XY" * }) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts b/packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts index bb52f9229b..8d61f46332 100644 --- a/packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts +++ b/packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts @@ -15,7 +15,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/orders/{id}/shipping-methods * operationId: "PostOrdersOrderShippingMethods" * summary: "Add a Shipping Method" - * description: "Adds a Shipping Method to an Order. If another Shipping Method exists with the same Shipping Profile, the previous Shipping Method will be replaced." + * description: "Add a Shipping Method to an Order. If another Shipping Method exists with the same Shipping Profile, the previous Shipping Method will be replaced." * parameters: * - (path) id=* {string} The ID of the Order. * - (query) expand {string} Comma-separated relations that should be expanded in the returned order. @@ -42,7 +42,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -105,6 +105,7 @@ export default async (req, res) => { /** * @schema AdminPostOrdersOrderShippingMethodsReq * type: object + * description: "The shipping method's details." * required: * - price * - option_id @@ -115,7 +116,7 @@ export default async (req, res) => { * option_id: * type: string * description: The ID of the Shipping Option to create the Shipping Method from. - * date: + * data: * type: object * description: The data required for the Shipping Option to create a Shipping Method. This depends on the Fulfillment Provider. */ diff --git a/packages/medusa/src/api/routes/admin/orders/archive-order.ts b/packages/medusa/src/api/routes/admin/orders/archive-order.ts index 8c61e9175d..dbd2b86ed6 100644 --- a/packages/medusa/src/api/routes/admin/orders/archive-order.ts +++ b/packages/medusa/src/api/routes/admin/orders/archive-order.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.archive(orderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-claim.ts b/packages/medusa/src/api/routes/admin/orders/cancel-claim.ts index 335804ebe3..931d68fd72 100644 --- a/packages/medusa/src/api/routes/admin/orders/cancel-claim.ts +++ b/packages/medusa/src/api/routes/admin/orders/cancel-claim.ts @@ -32,7 +32,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.cancelClaim(orderId, claimId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts index 4ba7645158..6615d48c01 100644 --- a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts +++ b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts @@ -13,7 +13,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel * operationId: "PostOrdersClaimFulfillmentsCancel" * summary: "Cancel Claim's Fulfillment" - * description: "Cancel a claim's fulfillment and change its status." + * description: "Cancel a claim's fulfillment and change its fulfillment status to `canceled`." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the order the claim is associated with. @@ -34,7 +34,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.cancelClaimFulfillment(orderId, claimId, fulfillmentId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts index d0856da2b2..3605336255 100644 --- a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts +++ b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts @@ -13,7 +13,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel * operationId: "PostOrdersSwapFulfillmentsCancel" * summary: "Cancel Swap's Fulfilmment" - * description: "Cancel a swap's fulfillment and change its status." + * description: "Cancel a swap's fulfillment and change its fulfillment status to `canceled`." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the order the swap is associated with. @@ -34,7 +34,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.cancelSwapFulfillment(orderId, swapId, fulfillmentId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts index f986b0283a..7b9015f21c 100644 --- a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts +++ b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts @@ -16,7 +16,7 @@ import { promiseAll } from "@medusajs/utils" * @oas [post] /admin/orders/{id}/fulfillments/{fulfillment_id}/cancel * operationId: "PostOrdersOrderFulfillmentsCancel" * summary: "Cancel a Fulfilmment" - * description: "Cancel an order's fulfillment and change its status." + * description: "Cancel an order's fulfillment and change its fulfillment status to `canceled`." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Order. @@ -36,7 +36,7 @@ import { promiseAll } from "@medusajs/utils" * medusa.admin.orders.cancelFulfillment(orderId, fulfillmentId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-order.ts b/packages/medusa/src/api/routes/admin/orders/cancel-order.ts index 343bc97bc0..8d46efa2c6 100644 --- a/packages/medusa/src/api/routes/admin/orders/cancel-order.ts +++ b/packages/medusa/src/api/routes/admin/orders/cancel-order.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.cancel(orderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-swap.ts b/packages/medusa/src/api/routes/admin/orders/cancel-swap.ts index 9afde421d6..818ef39acd 100644 --- a/packages/medusa/src/api/routes/admin/orders/cancel-swap.ts +++ b/packages/medusa/src/api/routes/admin/orders/cancel-swap.ts @@ -32,7 +32,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.cancelSwap(orderId, swapId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/capture-payment.ts b/packages/medusa/src/api/routes/admin/orders/capture-payment.ts index db3b448ed9..f2d310376e 100644 --- a/packages/medusa/src/api/routes/admin/orders/capture-payment.ts +++ b/packages/medusa/src/api/routes/admin/orders/capture-payment.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.capturePayment(orderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/complete-order.ts b/packages/medusa/src/api/routes/admin/orders/complete-order.ts index 31d79218e0..dc9af196bf 100644 --- a/packages/medusa/src/api/routes/admin/orders/complete-order.ts +++ b/packages/medusa/src/api/routes/admin/orders/complete-order.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.complete(orderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts b/packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts index b975670446..129e0d445d 100644 --- a/packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts +++ b/packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts @@ -8,7 +8,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/orders/{id}/claims/{claim_id}/shipments * operationId: "PostOrdersOrderClaimsClaimShipments" * summary: "Ship a Claim's Fulfillment" - * description: "Mark a claim's fulfillment as shipped. This changes the claim's fulfillment status to either `shipped` or `partially_shipped`, depending on + * description: "Create a shipment for the claim and mark its fulfillment as shipped. This changes the claim's fulfillment status to either `partially_shipped` or `shipped`, depending on * whether all the items were shipped." * x-authenticated: true * externalDocs: @@ -39,7 +39,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/create-claim.ts b/packages/medusa/src/api/routes/admin/orders/create-claim.ts index 366dd045e9..b87861ca8a 100644 --- a/packages/medusa/src/api/routes/admin/orders/create-claim.ts +++ b/packages/medusa/src/api/routes/admin/orders/create-claim.ts @@ -58,7 +58,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -309,12 +309,14 @@ export default async (req, res) => { /** * @schema AdminPostOrdersOrderClaimsReq * type: object + * description: "The details of the claim to be created." * required: * - type * - claim_items * properties: * type: - * description: "The type of the Claim. This will determine how the Claim is treated: `replace` Claims will result in a Fulfillment with new items being created, while a `refund` Claim will refund the amount paid for the claimed items." + * description: >- + * The type of the Claim. This will determine how the Claim is treated: `replace` Claims will result in a Fulfillment with new items being created, while a `refund` Claim will refund the amount paid for the claimed items. * type: string * enum: * - replace @@ -406,6 +408,9 @@ export default async (req, res) => { * no_notification: * description: If set to true no notification will be send related to this Claim. * type: boolean + * return_location_id: + * description: The ID of the location used for the associated return. + * type: string * metadata: * description: An optional set of key-value pairs to hold additional information. * type: object @@ -464,11 +469,20 @@ export class AdminPostOrdersOrderClaimsReq { metadata?: Record } +/** + * The return's shipping method details. + */ class ReturnShipping { + /** + * The ID of the shipping option used for the return. + */ @IsString() @IsOptional() option_id?: string + /** + * The shipping method's price. + */ @IsInt() @IsOptional() price?: number diff --git a/packages/medusa/src/api/routes/admin/orders/create-fulfillment.ts b/packages/medusa/src/api/routes/admin/orders/create-fulfillment.ts index 4b3327ed58..73ffa4144a 100644 --- a/packages/medusa/src/api/routes/admin/orders/create-fulfillment.ts +++ b/packages/medusa/src/api/routes/admin/orders/create-fulfillment.ts @@ -25,7 +25,8 @@ import { promiseAll } from "@medusajs/utils" * @oas [post] /admin/orders/{id}/fulfillment * operationId: "PostOrdersOrderFulfillments" * summary: "Create a Fulfillment" - * description: "Create a Fulfillment of an Order using the fulfillment provider." + * description: "Create a Fulfillment of an Order using the fulfillment provider, and change the order's fulfillment status to either `partially_fulfilled` or `fulfilled`, depending on + * whether all the items were fulfilled." * x-authenticated: true * externalDocs: * description: Fulfillments of orders @@ -59,7 +60,7 @@ import { promiseAll } from "@medusajs/utils" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -206,6 +207,7 @@ export const updateInventoryAndReservations = async ( /** * @schema AdminPostOrdersOrderFulfillmentsReq * type: object + * description: "The details of the fulfillment to be created." * required: * - items * properties: @@ -224,8 +226,12 @@ export const updateInventoryAndReservations = async ( * quantity: * description: The quantity of the Line Item to fulfill. * type: integer + * location_id: + * type: string + * description: "The ID of the location where the items will be fulfilled from." * no_notification: - * description: If set to `true`, no notification will be sent to the customer related to this fulfillment. + * description: >- + * If set to `true`, no notification will be sent to the customer related to this fulfillment. * type: boolean * metadata: * description: An optional set of key-value pairs to hold additional information. diff --git a/packages/medusa/src/api/routes/admin/orders/create-shipment.ts b/packages/medusa/src/api/routes/admin/orders/create-shipment.ts index 2e7c66524a..e5e06b90af 100644 --- a/packages/medusa/src/api/routes/admin/orders/create-shipment.ts +++ b/packages/medusa/src/api/routes/admin/orders/create-shipment.ts @@ -16,7 +16,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/orders/{id}/shipment * operationId: "PostOrdersOrderShipment" * summary: "Ship a Fulfillment" - * description: "Mark a fulfillment as shipped. This changes the order's fulfillment status to either `shipped` or `partially_shipped`, depending on + * description: "Create a shipment and mark a fulfillment as shipped. This changes the order's fulfillment status to either `partially_shipped` or `shipped`, depending on * whether all the items were shipped." * x-authenticated: true * externalDocs: @@ -46,7 +46,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts b/packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts index 69ecc366ee..1a21bcc069 100644 --- a/packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts +++ b/packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts @@ -16,7 +16,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /admin/orders/{id}/swaps/{swap_id}/shipments * operationId: "PostOrdersOrderSwapsSwapShipments" * summary: "Ship a Swap's Fulfillment" - * description: "RMark a swap's fulfillment as shipped. This changes the swap's fulfillment status to either `shipped` or `partially_shipped`, depending on + * description: "Create a shipment for a swap and mark its fulfillment as shipped. This changes the swap's fulfillment status to either `partially_shipped` or `shipped`, depending on * whether all the items were shipped." * x-authenticated: true * externalDocs: @@ -42,12 +42,12 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * import Medusa from "@medusajs/medusa-js" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token - * medusa.admin.orders.createSwapShipment(order_id, swap_id, { + * medusa.admin.orders.createSwapShipment(orderId, swapId, { * fulfillment_id * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/create-swap.ts b/packages/medusa/src/api/routes/admin/orders/create-swap.ts index 9f07ad4c91..142af710f5 100644 --- a/packages/medusa/src/api/routes/admin/orders/create-swap.ts +++ b/packages/medusa/src/api/routes/admin/orders/create-swap.ts @@ -61,7 +61,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -319,6 +319,9 @@ export default async (req, res) => { * quantity: * description: The quantity of the Product Variant. * type: integer + * sales_channel_id: + * type: string + * description: "The ID of the sales channel associated with the swap." * custom_shipping_options: * description: An array of custom shipping options to potentially create a Shipping Method from to send the additional items. * type: array @@ -335,10 +338,15 @@ export default async (req, res) => { * description: The custom price of the Shipping Option. * type: integer * no_notification: - * description: If set to `true`, no notification will be sent to the customer related to this Swap. + * description: >- + * If set to `true`, no notification will be sent to the customer related to this Swap. * type: boolean + * return_location_id: + * type: string + * description: "The ID of the location used for the associated return." * allow_backorder: - * description: If set to `true`, swaps can be completed with items out of stock + * description: >- + * If set to `true`, swaps can be completed with items out of stock * type: boolean * default: true */ @@ -403,11 +411,20 @@ class ReturnItem { note?: string } +/** + * The return's shipping method details. + */ class ReturnShipping { + /** + * The ID of the shipping option used for the return. + */ @IsString() @IsNotEmpty() option_id: string + /** + * The shipping method's price. + */ @IsInt() @IsOptional() price?: number diff --git a/packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts b/packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts index 589a87cbde..d6d7e22369 100644 --- a/packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts +++ b/packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts @@ -14,7 +14,8 @@ import { updateInventoryAndReservations } from "./create-fulfillment" * @oas [post] /admin/orders/{id}/claims/{claim_id}/fulfillments * operationId: "PostOrdersOrderClaimsClaimFulfillments" * summary: "Create a Claim Fulfillment" - * description: "Create a Fulfillment for a Claim." + * description: "Create a Fulfillment for a Claim, and change its fulfillment status to `partially_fulfilled` or `fulfilled` depending on whether all the items were fulfilled. + * It may also change the status to `requires_action` if any actions are required." * x-authenticated: true * externalDocs: * description: Fulfill a claim @@ -43,7 +44,7 @@ import { updateInventoryAndReservations } from "./create-fulfillment" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -148,8 +149,12 @@ export default async (req, res) => { * description: "Learn about the metadata attribute, and how to delete and update it." * url: "https://docs.medusajs.com/development/entities/overview#metadata-attribute" * no_notification: - * description: If set to `true`, no notification will be sent to the customer related to this Claim. + * description: >- + * If set to `true`, no notification will be sent to the customer related to this Claim. * type: boolean + * location_id: + * description: "The ID of the fulfillment's location." + * type: string */ export class AdminPostOrdersOrderClaimsClaimFulfillmentsReq { @IsObject() diff --git a/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts b/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts index 838bc16e0e..bdb5b9d75a 100644 --- a/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts +++ b/packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts @@ -15,7 +15,8 @@ import { updateInventoryAndReservations } from "./create-fulfillment" * @oas [post] /admin/orders/{id}/swaps/{swap_id}/fulfillments * operationId: "PostOrdersOrderSwapsSwapFulfillments" * summary: "Create a Swap Fulfillment" - * description: "Create a Fulfillment for a Swap." + * description: "Create a Fulfillment for a Swap and change its fulfillment status to `fulfilled`. If it requires any additional actions, + * its fulfillment status may change to `requires_action`." * x-authenticated: true * externalDocs: * description: Handling a swap's fulfillment @@ -45,7 +46,7 @@ import { updateInventoryAndReservations } from "./create-fulfillment" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -157,6 +158,9 @@ export default async (req, res) => { * no_notification: * description: If set to `true`, no notification will be sent to the customer related to this swap. * type: boolean + * location_id: + * description: "The ID of the fulfillment's location." + * type: string */ export class AdminPostOrdersOrderSwapsSwapFulfillmentsReq { @IsObject() diff --git a/packages/medusa/src/api/routes/admin/orders/get-order.ts b/packages/medusa/src/api/routes/admin/orders/get-order.ts index 34d122ad11..2faf59ea28 100644 --- a/packages/medusa/src/api/routes/admin/orders/get-order.ts +++ b/packages/medusa/src/api/routes/admin/orders/get-order.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.retrieve(orderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/index.ts b/packages/medusa/src/api/routes/admin/orders/index.ts index 710af1024a..ade9cab810 100644 --- a/packages/medusa/src/api/routes/admin/orders/index.ts +++ b/packages/medusa/src/api/routes/admin/orders/index.ts @@ -484,6 +484,7 @@ export default (app, featureFlagRouter: FlagRouter) => { /** * @schema AdminOrdersRes * type: object + * description: "The order's details." * x-expanded-relations: * field: order * relations: @@ -602,6 +603,7 @@ export type AdminOrdersRes = { /** * @schema AdminOrdersListRes * type: object + * description: "The list of orders with pagination fields." * x-expanded-relations: * field: orders * relations: @@ -779,4 +781,3 @@ export * from "./refund-payment" export * from "./request-return" export * from "./update-claim" export * from "./update-order" - diff --git a/packages/medusa/src/api/routes/admin/orders/list-orders.ts b/packages/medusa/src/api/routes/admin/orders/list-orders.ts index b643237592..8adca69618 100644 --- a/packages/medusa/src/api/routes/admin/orders/list-orders.ts +++ b/packages/medusa/src/api/routes/admin/orders/list-orders.ts @@ -165,7 +165,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.list() * .then(({ orders, limit, offset, count }) => { * console.log(orders.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -217,21 +217,38 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved orders. + */ export class AdminGetOrdersParams extends AdminListOrdersSelector { + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset = 0 + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 50 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string + /** + * {@inheritDoc FindParams.fields} + */ @IsString() @IsOptional() fields?: string diff --git a/packages/medusa/src/api/routes/admin/orders/process-swap-payment.ts b/packages/medusa/src/api/routes/admin/orders/process-swap-payment.ts index 51903cb5a9..39c1eeac75 100644 --- a/packages/medusa/src/api/routes/admin/orders/process-swap-payment.ts +++ b/packages/medusa/src/api/routes/admin/orders/process-swap-payment.ts @@ -32,7 +32,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.admin.orders.processSwapPayment(orderId, swapId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/refund-payment.ts b/packages/medusa/src/api/routes/admin/orders/refund-payment.ts index 4fc3f98a3f..ff44959d21 100644 --- a/packages/medusa/src/api/routes/admin/orders/refund-payment.ts +++ b/packages/medusa/src/api/routes/admin/orders/refund-payment.ts @@ -42,7 +42,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -119,7 +119,8 @@ export default async (req, res) => { * description: A note with additional details about the Refund. * type: string * no_notification: - * description: If set to `true`, no notification will be sent to the customer related to this Refund. + * description: >- + * If set to `true`, no notification will be sent to the customer related to this Refund. * type: boolean */ export class AdminPostOrdersOrderRefundsReq { diff --git a/packages/medusa/src/api/routes/admin/orders/request-return.ts b/packages/medusa/src/api/routes/admin/orders/request-return.ts index 0d9c9d99e5..8d9c4a2bf5 100644 --- a/packages/medusa/src/api/routes/admin/orders/request-return.ts +++ b/packages/medusa/src/api/routes/admin/orders/request-return.ts @@ -57,7 +57,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -344,11 +344,15 @@ type ReturnObj = { * type: boolean * default: false * no_notification: - * description: If set to `true`, no notification will be sent to the customer related to this Return. + * description: >- + * If set to `true`, no notification will be sent to the customer related to this Return. * type: boolean * refund: * description: The amount to refund. * type: integer + * location_id: + * description: "The ID of the location used for the return." + * type: string */ export class AdminPostOrdersOrderReturnsReq { @IsArray() @@ -382,11 +386,20 @@ export class AdminPostOrdersOrderReturnsReq { location_id?: string } +/** + * The return's shipping method details. + */ class ReturnShipping { + /** + * The ID of the shipping option used for the return. + */ @IsString() @IsOptional() option_id?: string + /** + * The shipping method's price. + */ @IsInt() @IsOptional() price?: number diff --git a/packages/medusa/src/api/routes/admin/orders/update-claim.ts b/packages/medusa/src/api/routes/admin/orders/update-claim.ts index 03bfe5a1da..83dbce483f 100644 --- a/packages/medusa/src/api/routes/admin/orders/update-claim.ts +++ b/packages/medusa/src/api/routes/admin/orders/update-claim.ts @@ -47,7 +47,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/orders/update-order.ts b/packages/medusa/src/api/routes/admin/orders/update-order.ts index 9169ead138..4fc44f5823 100644 --- a/packages/medusa/src/api/routes/admin/orders/update-order.ts +++ b/packages/medusa/src/api/routes/admin/orders/update-order.ts @@ -45,7 +45,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -106,7 +106,7 @@ export default async (req, res) => { * type: object * properties: * email: - * description: the email associated with the order + * description: The email associated with the order * type: string * billing_address: * description: The order's billing address @@ -162,7 +162,8 @@ export default async (req, res) => { * $ref: "#/components/schemas/LineItem" * description: Items to ship * no_notification: - * description: If set to `true`, no notification will be sent to the customer related to this order. + * description: >- + * If set to `true`, no notification will be sent to the customer related to this order. * type: boolean */ export class AdminPostOrdersOrderReq { @@ -211,36 +212,66 @@ export class AdminPostOrdersOrderReq { no_notification?: boolean } +/** + * The attributes to update in the order's payment method. + */ class PaymentMethod { + /** + * The ID of the payment provider used in the order. + */ @IsString() @IsOptional() provider_id?: string + /** + * The data to attach to the payment. + */ @IsObject() @IsOptional() data?: Record } +/** + * The attributes to update in the order's shipping method. + */ class ShippingMethod { + /** + * The ID of the shipping provider used in the order. + */ @IsString() @IsOptional() provider_id?: string + /** + * The ID of the shipping profile used in the order. + */ @IsString() @IsOptional() profile_id?: string + /** + * The price of the shipping method. + */ @IsInt() @IsOptional() price?: number + /** + * The data to attach to the shipping method. + */ @IsObject() @IsOptional() data?: Record + /** + * The line items associated with this shipping methods. + */ @IsArray() @IsOptional() items?: Record[] } +/** + * Parameters used to configure the retrieved order. + */ export class AdminPostOrdersOrderParams extends FindParams {} diff --git a/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts index 3b313d6cd8..2941a58e33 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts @@ -18,9 +18,9 @@ import { PaymentCollectionService } from "../../../../services" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.paymentCollections.delete(paymentCollectionId) - * .then(({ id, object, deleted }) => { - * console.log(id) - * }) + * .then(({ id, object, deleted }) => { + * console.log(id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts index d4d7b77848..83fb077c6e 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts @@ -22,9 +22,9 @@ import { FindParams } from "../../../../types/common" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.paymentCollections.retrieve(paymentCollectionId) - * .then(({ payment_collection }) => { - * console.log(payment_collection.id) - * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/payment-collections/index.ts b/packages/medusa/src/api/routes/admin/payment-collections/index.ts index 7d1adbedd7..c2cb9cd9a9 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/index.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/index.ts @@ -88,6 +88,7 @@ export type AdminPaymentCollectionsRes = { /** * @schema AdminPaymentCollectionDeleteRes * type: object + * description: "The details of deleting a payment collection." * required: * - id * - object diff --git a/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts index 3bcc476984..b0482acaaa 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts @@ -19,9 +19,9 @@ import { PaymentCollectionService } from "../../../../services" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.paymentCollections.markAsAuthorized(paymentCollectionId) - * .then(({ payment_collection }) => { - * console.log(payment_collection.id) - * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts index b28d411e36..bc3f0e1850 100644 --- a/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts +++ b/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts @@ -28,9 +28,9 @@ import { PaymentCollectionService } from "../../../../services" * medusa.admin.paymentCollections.update(paymentCollectionId, { * description * }) - * .then(({ payment_collection }) => { - * console.log(payment_collection.id) - * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/payments/capture-payment.ts b/packages/medusa/src/api/routes/admin/payments/capture-payment.ts index f3975ac5c9..658bff679f 100644 --- a/packages/medusa/src/api/routes/admin/payments/capture-payment.ts +++ b/packages/medusa/src/api/routes/admin/payments/capture-payment.ts @@ -20,7 +20,7 @@ import { PaymentService } from "../../../../services" * medusa.admin.payments.capturePayment(paymentId) * .then(({ payment }) => { * console.log(payment.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/payments/get-payment.ts b/packages/medusa/src/api/routes/admin/payments/get-payment.ts index bb0e1e1be2..90e383b4f6 100644 --- a/packages/medusa/src/api/routes/admin/payments/get-payment.ts +++ b/packages/medusa/src/api/routes/admin/payments/get-payment.ts @@ -22,7 +22,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.payments.retrieve(paymentId) * .then(({ payment }) => { * console.log(payment.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/payments/index.ts b/packages/medusa/src/api/routes/admin/payments/index.ts index 8ac9ee112a..b1e168ca89 100644 --- a/packages/medusa/src/api/routes/admin/payments/index.ts +++ b/packages/medusa/src/api/routes/admin/payments/index.ts @@ -55,6 +55,7 @@ export const defaultPaymentFields = [ /** * @schema AdminPaymentRes * type: object + * description: "The payment's details." * required: * - payment * properties: @@ -69,11 +70,12 @@ export type AdminPaymentRes = { /** * @schema AdminRefundRes * type: object + * description: "The refund's details." * required: * - refund * properties: * refund: - * description: "Refund details" + * description: "Refund details." * $ref: "#/components/schemas/Refund" */ export type AdminRefundRes = { diff --git a/packages/medusa/src/api/routes/admin/payments/refund-payment.ts b/packages/medusa/src/api/routes/admin/payments/refund-payment.ts index 193e81e404..4a85689bd5 100644 --- a/packages/medusa/src/api/routes/admin/payments/refund-payment.ts +++ b/packages/medusa/src/api/routes/admin/payments/refund-payment.ts @@ -38,7 +38,7 @@ import { PaymentService } from "../../../../services" * }) * .then(({ payment }) => { * console.log(payment.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/add-prices-batch.ts b/packages/medusa/src/api/routes/admin/price-lists/add-prices-batch.ts index a18c2acc41..64bd889064 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/add-prices-batch.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/add-prices-batch.ts @@ -12,7 +12,7 @@ import { EntityManager } from "typeorm" * @oas [post] /admin/price-lists/{id}/prices/batch * operationId: "PostPriceListsPriceListPricesBatch" * summary: "Add or Update Prices" - * description: "Add or update a list of prices in a Price List" + * description: "Add or update a list of prices in a Price List." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Price List. @@ -41,7 +41,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ price_list }) => { * console.log(price_list.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -144,7 +144,8 @@ export default async (req, res) => { * description: The maximum quantity for which the price will be used. * type: integer * override: - * description: "If set to `true`, the prices will replace all existing prices associated with the Price List." + * description: >- + * If set to `true`, the prices will replace all existing prices associated with the Price List. * type: boolean */ export class AdminPostPriceListPricesPricesReq { diff --git a/packages/medusa/src/api/routes/admin/price-lists/create-price-list.ts b/packages/medusa/src/api/routes/admin/price-lists/create-price-list.ts index a3f5aedcb4..395c255072 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/create-price-list.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/create-price-list.ts @@ -60,7 +60,7 @@ import { PriceList } from "../../../../models" * }) * .then(({ price_list }) => { * console.log(price_list.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -159,7 +159,8 @@ class CustomerGroup { * - sale * - override * status: - * description: "The status of the Price List. If the status is set to `draft`, the prices created in the price list will not be available of the customer." + * description: >- + * The status of the Price List. If the status is set to `draft`, the prices created in the price list will not be available of the customer. * type: string * enum: * - active diff --git a/packages/medusa/src/api/routes/admin/price-lists/delete-price-list.ts b/packages/medusa/src/api/routes/admin/price-lists/delete-price-list.ts index 34dfd94da6..54af5cfaaf 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/delete-price-list.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/delete-price-list.ts @@ -21,7 +21,7 @@ import PriceListService from "../../../../services/price-list" * medusa.admin.priceLists.delete(priceListId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/delete-prices-batch.ts b/packages/medusa/src/api/routes/admin/price-lists/delete-prices-batch.ts index 51209eee24..5de013889f 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/delete-prices-batch.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/delete-prices-batch.ts @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ ids, object, deleted }) => { * console.log(ids.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/delete-product-prices.ts b/packages/medusa/src/api/routes/admin/price-lists/delete-product-prices.ts index e58f147d4c..6c424c9624 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/delete-product-prices.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/delete-product-prices.ts @@ -22,7 +22,7 @@ import PriceListService from "../../../../services/price-list" * medusa.admin.priceLists.deleteProductPrices(priceListId, productId) * .then(({ ids, object, deleted }) => { * console.log(ids.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/delete-products-prices-batch.ts b/packages/medusa/src/api/routes/admin/price-lists/delete-products-prices-batch.ts index 41c432a326..4209879087 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/delete-products-prices-batch.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/delete-products-prices-batch.ts @@ -29,7 +29,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ ids, object, deleted }) => { * console.log(ids.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/delete-variant-prices.ts b/packages/medusa/src/api/routes/admin/price-lists/delete-variant-prices.ts index bd1237cc81..4ba20c9750 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/delete-variant-prices.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/delete-variant-prices.ts @@ -5,7 +5,7 @@ import PriceListService from "../../../../services/price-list" * @oas [delete] /admin/price-lists/{id}/variants/{variant_id}/prices * operationId: "DeletePriceListsPriceListVariantsVariantPrices" * summary: "Delete a Variant's Prices" - * description: "Delete all the prices related to a specific variant in a price list" + * description: "Delete all the prices related to a specific variant in a price list." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Price List. @@ -22,7 +22,7 @@ import PriceListService from "../../../../services/price-list" * medusa.admin.priceLists.deleteVariantPrices(priceListId, variantId) * .then(({ ids, object, deleted }) => { * console.log(ids); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/get-price-list.ts b/packages/medusa/src/api/routes/admin/price-lists/get-price-list.ts index 910fcc68e1..0939d06b0d 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/get-price-list.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/get-price-list.ts @@ -23,7 +23,7 @@ import PriceListService from "../../../../services/price-list" * medusa.admin.priceLists.retrieve(priceListId) * .then(({ price_list }) => { * console.log(price_list.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/price-lists/index.ts b/packages/medusa/src/api/routes/admin/price-lists/index.ts index 621f7d47d4..f4ff52921a 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/index.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/index.ts @@ -108,6 +108,7 @@ export const defaultAdminPriceListRelations = [ /** * @schema AdminPriceListRes * type: object + * description: "The price list's details." * x-expanded-relations: * field: price_list * relations: @@ -127,6 +128,7 @@ export type AdminPriceListRes = { /** * @schema AdminPriceListDeleteBatchRes * type: object + * description: "The details of deleting a price list." * required: * - ids * - object @@ -134,9 +136,10 @@ export type AdminPriceListRes = { * properties: * ids: * type: array + * description: The IDs of the deleted prices. * items: * type: string - * description: The IDs of the deleted prices. + * description: The ID of a deleted price. * object: * type: string * description: The type of the object that was deleted. A price is also named `money-amount`. @@ -225,6 +228,7 @@ export type AdminPriceListDeleteRes = DeleteResponse /** * @schema AdminPriceListsListRes * type: object + * description: "The list of price lists with pagination fields." * required: * - price_lists * - count @@ -253,6 +257,7 @@ export type AdminPriceListsListRes = PaginatedResponse & { /** * @schema AdminPriceListsProductsListRes * type: object + * description: "The list of products with pagination fields." * x-expanded-relations: * field: products * relations: diff --git a/packages/medusa/src/api/routes/admin/price-lists/list-price-list-products.ts b/packages/medusa/src/api/routes/admin/price-lists/list-price-list-products.ts index 739b2b6c00..6fc229b553 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/list-price-list-products.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/list-price-list-products.ts @@ -146,7 +146,7 @@ import { pickBy } from "lodash" * medusa.admin.priceLists.listProducts(priceListId) * .then(({ products, limit, offset, count }) => { * console.log(products.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -204,65 +204,112 @@ export default async (req: Request, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved products associated with a price list. + * + * @property {number} limit - Limit the number of products returned in the list. Default is `50`. + */ // eslint-disable-next-line max-len export class AdminGetPriceListsPriceListProductsParams extends extendedFindParamsMixin( { limit: 50 } ) { + /** + * ID to filter products by. + */ @IsString() @IsOptional() id?: string + /** + * Search term to search products' title, description, product variant's title and sku, and product collection's title. + */ @IsString() @IsOptional() q?: string + /** + * Statuses to filter products by. + */ @IsOptional() @IsEnum(ProductStatus, { each: true }) status?: ProductStatus[] + /** + * Filter products by their associated collection ID. + */ @IsArray() @IsOptional() collection_id?: string[] + /** + * Tags to filter products by. + */ @IsArray() @IsOptional() tags?: string[] + /** + * Title to filter products by. + */ @IsString() @IsOptional() title?: string + /** + * Description to filter products by. + */ @IsString() @IsOptional() description?: string + /** + * Handle to filter products by. + */ @IsString() @IsOptional() handle?: string + /** + * Filter products by whether they're gift cards. + */ @IsBoolean() @IsOptional() @Type(() => Boolean) is_giftcard?: string + /** + * Type to filter products by. + */ @IsString() @IsOptional() type?: string + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string + /** + * Date filters to apply on the products' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the products' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the products' `deleted_at` date. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/api/routes/admin/price-lists/list-price-lists.ts b/packages/medusa/src/api/routes/admin/price-lists/list-price-lists.ts index a90b6dc631..d868794fb8 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/list-price-lists.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/list-price-lists.ts @@ -128,7 +128,7 @@ import { Type } from "class-transformer" * medusa.admin.priceLists.list() * .then(({ price_lists, limit, offset, count }) => { * console.log(price_lists.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -179,22 +179,39 @@ export default async (req: Request, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved price lists. + */ // eslint-disable-next-line max-len export class AdminGetPriceListPaginationParams extends FilterablePriceListProps { + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset?: number = 0 + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 10 + */ @IsNumber() @IsOptional() @Type(() => Number) limit?: number = 10 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string diff --git a/packages/medusa/src/api/routes/admin/price-lists/update-price-list.ts b/packages/medusa/src/api/routes/admin/price-lists/update-price-list.ts index 1c1f6c77f3..371585cfde 100644 --- a/packages/medusa/src/api/routes/admin/price-lists/update-price-list.ts +++ b/packages/medusa/src/api/routes/admin/price-lists/update-price-list.ts @@ -48,7 +48,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ price_list }) => { * console.log(price_list.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -140,7 +140,8 @@ class CustomerGroup { * - sale * - override * status: - * description: "The status of the Price List. If the status is set to `draft`, the prices created in the price list will not be available of the customer." + * description: >- + * The status of the Price List. If the status is set to `draft`, the prices created in the price list will not be available of the customer. * type: string * enum: * - active diff --git a/packages/medusa/src/api/routes/admin/product-categories/add-products-batch.ts b/packages/medusa/src/api/routes/admin/product-categories/add-products-batch.ts index db5db4f187..06b1f42998 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/add-products-batch.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/add-products-batch.ts @@ -42,7 +42,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ product_category }) => { * console.log(product_category.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/product-categories/create-product-category.ts b/packages/medusa/src/api/routes/admin/product-categories/create-product-category.ts index 5d342b085d..4dae41d6ea 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/create-product-category.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/create-product-category.ts @@ -36,7 +36,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ product_category }) => { * console.log(product_category.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -113,10 +113,12 @@ export default async (req: Request, res: Response) => { * description: The handle of the product category. If none is provided, the kebab-case version of the name will be used. This field can be used as a slug in URLs. * is_internal: * type: boolean - * description: If set to `true`, the product category will only be available to admins. + * description: >- + * If set to `true`, the product category will only be available to admins. * is_active: * type: boolean - * description: If set to `false`, the product category will not be available in the storefront. + * description: >- + * If set to `false`, the product category will not be available in the storefront. * parent_category_id: * type: string * description: The ID of the parent product category diff --git a/packages/medusa/src/api/routes/admin/product-categories/delete-product-category.ts b/packages/medusa/src/api/routes/admin/product-categories/delete-product-category.ts index 6fd317ce2a..d9879025b4 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/delete-product-category.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/delete-product-category.ts @@ -24,7 +24,7 @@ import { ProductCategoryService } from "../../../../services" * medusa.admin.productCategories.delete(productCategoryId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/product-categories/delete-products-batch.ts b/packages/medusa/src/api/routes/admin/product-categories/delete-products-batch.ts index 96604dcf02..be1c519d32 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/delete-products-batch.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/delete-products-batch.ts @@ -42,7 +42,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ product_category }) => { * console.log(product_category.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/product-categories/get-product-category.ts b/packages/medusa/src/api/routes/admin/product-categories/get-product-category.ts index 51ea0f4574..553a949405 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/get-product-category.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/get-product-category.ts @@ -28,7 +28,7 @@ import { defaultAdminProductCategoryRelations } from "." * medusa.admin.productCategories.retrieve(productCategoryId) * .then(({ product_category }) => { * console.log(product_category.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/product-categories/index.ts b/packages/medusa/src/api/routes/admin/product-categories/index.ts index 2f4a362f57..cb86923f59 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/index.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/index.ts @@ -154,6 +154,7 @@ export const defaultProductCategoryFields = [ /** * @schema AdminProductCategoriesCategoryRes * type: object + * description: "The product category's details." * x-expanded-relations: * field: product_category * relations: @@ -195,6 +196,7 @@ export type AdminProductCategoriesCategoryDeleteRes = DeleteResponse /** * @schema AdminProductCategoriesListRes * type: object + * description: "The list of product categories with pagination fields." * x-expanded-relations: * field: product_categories * relations: diff --git a/packages/medusa/src/api/routes/admin/product-categories/list-product-categories.ts b/packages/medusa/src/api/routes/admin/product-categories/list-product-categories.ts index 178f5413b9..4074c5dd70 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/list-product-categories.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/list-product-categories.ts @@ -37,7 +37,7 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean" * medusa.admin.productCategories.list() * .then(({ product_categories, limit, offset, count }) => { * console.log(product_categories.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -89,31 +89,54 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product categories. + * + * @property {number} limit - Limit the number of product categories returned in the list. The default is `100`. + */ export class AdminGetProductCategoriesParams extends extendedFindParamsMixin({ limit: 100, offset: 0, }) { + /** + * Search term to search product categories' names and handles. + */ @IsString() @IsOptional() q?: string + /** + * Handle to filter product categories by. + */ @IsString() @IsOptional() handle?: string + /** + * Whether to include child product categories in the response. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value)) include_descendants_tree?: boolean + /** + * Filter product categories by whether they're internal. + */ @IsString() @IsOptional() is_internal?: boolean + /** + * Filter product categories by whether they're active. + */ @IsString() @IsOptional() is_active?: boolean + /** + * Filter product categories by their associated parent ID. + */ @IsString() @IsOptional() @Transform(({ value }) => { diff --git a/packages/medusa/src/api/routes/admin/product-categories/update-product-category.ts b/packages/medusa/src/api/routes/admin/product-categories/update-product-category.ts index 8ce9e5be99..69ca797df9 100644 --- a/packages/medusa/src/api/routes/admin/product-categories/update-product-category.ts +++ b/packages/medusa/src/api/routes/admin/product-categories/update-product-category.ts @@ -37,7 +37,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ product_category }) => { * console.log(product_category.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/product-tags/index.ts b/packages/medusa/src/api/routes/admin/product-tags/index.ts index 45538d5a50..0ea434f5a8 100644 --- a/packages/medusa/src/api/routes/admin/product-tags/index.ts +++ b/packages/medusa/src/api/routes/admin/product-tags/index.ts @@ -34,6 +34,7 @@ export const defaultAdminProductTagsRelations = [] /** * @schema AdminProductTagsListRes * type: object + * description: "The list of product tags with pagination fields." * required: * - product_tags * - count diff --git a/packages/medusa/src/api/routes/admin/product-tags/list-product-tags.ts b/packages/medusa/src/api/routes/admin/product-tags/list-product-tags.ts index 864247678b..f4114b1594 100644 --- a/packages/medusa/src/api/routes/admin/product-tags/list-product-tags.ts +++ b/packages/medusa/src/api/routes/admin/product-tags/list-product-tags.ts @@ -96,7 +96,7 @@ import { Request, Response } from "express" * medusa.admin.productTags.list() * .then(({ product_tags }) => { * console.log(product_tags.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -146,43 +146,78 @@ export default async (req: Request, res: Response) => { }) } +/** + * {@inheritDoc FindPaginationParams} + */ export class AdminGetProductTagsPaginationParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 10 + */ @IsNumber() @IsOptional() @Type(() => Number) limit = 10 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset = 0 } +/** + * Parameters used to filter and configure the pagination of the retrieved product tags. + */ export class AdminGetProductTagsParams extends AdminGetProductTagsPaginationParams { + /** + * IDs to filter product tags by. + */ @IsOptional() @IsType([String, [String], StringComparisonOperator]) id?: string | string[] | StringComparisonOperator + /** + * Search term to search product tags' value. + */ @IsString() @IsOptional() q?: string + /** + * Values to search product tags by. + */ @IsOptional() @IsType([String, [String], StringComparisonOperator]) value?: string | string[] | StringComparisonOperator + /** + * Date filters to apply on the product tags' `created_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() created_at?: DateComparisonOperator + /** + * Date filters to apply on the product tags' `updated_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() updated_at?: DateComparisonOperator + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string + /** + * Filter product tags by their associated discount condition's ID. + */ @IsString() @IsOptional() discount_condition_id?: string diff --git a/packages/medusa/src/api/routes/admin/product-types/index.ts b/packages/medusa/src/api/routes/admin/product-types/index.ts index 988297e16a..c452b5ef62 100644 --- a/packages/medusa/src/api/routes/admin/product-types/index.ts +++ b/packages/medusa/src/api/routes/admin/product-types/index.ts @@ -34,6 +34,7 @@ export const defaultAdminProductTypeRelations = [] /** * @schema AdminProductTypesListRes * type: object + * description: "The list of product types with pagination fields." * required: * - product_types * - count diff --git a/packages/medusa/src/api/routes/admin/product-types/list-product-types.ts b/packages/medusa/src/api/routes/admin/product-types/list-product-types.ts index 55596bf62e..827e10f382 100644 --- a/packages/medusa/src/api/routes/admin/product-types/list-product-types.ts +++ b/packages/medusa/src/api/routes/admin/product-types/list-product-types.ts @@ -95,7 +95,7 @@ import ProductTypeService from "../../../../services/product-type" * medusa.admin.productTypes.list() * .then(({ product_types }) => { * console.log(product_types.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -147,32 +147,56 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product types. + */ // eslint-disable-next-line max-len export class AdminGetProductTypesParams extends FindPaginationParams { + /** + * IDs to filter product types by. + */ @IsType([String, [String], StringComparisonOperator]) @IsOptional() id?: string | string[] | StringComparisonOperator + /** + * Search terms to search product types' value. + */ @IsString() @IsOptional() q?: string + /** + * Values to filter product types by. + */ @IsType([String, [String], StringComparisonOperator]) @IsOptional() value?: string | string[] | StringComparisonOperator + /** + * Date filters to apply on the product types' `created_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() created_at?: DateComparisonOperator + /** + * Date filters to apply on the product types' `updated_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() updated_at?: DateComparisonOperator + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string + /** + * Filter product types by their associated discount condition's ID. + */ @IsString() @IsOptional() discount_condition_id?: string diff --git a/packages/medusa/src/api/routes/admin/products/add-option.ts b/packages/medusa/src/api/routes/admin/products/add-option.ts index 3ababaadff..2f531f628c 100644 --- a/packages/medusa/src/api/routes/admin/products/add-option.ts +++ b/packages/medusa/src/api/routes/admin/products/add-option.ts @@ -32,7 +32,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/create-product.ts b/packages/medusa/src/api/routes/admin/products/create-product.ts index 331a0abed3..2bd0279dde 100644 --- a/packages/medusa/src/api/routes/admin/products/create-product.ts +++ b/packages/medusa/src/api/routes/admin/products/create-product.ts @@ -76,7 +76,7 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators * }) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/delete-option.ts b/packages/medusa/src/api/routes/admin/products/delete-option.ts index 41e7f54a4d..d112baab03 100644 --- a/packages/medusa/src/api/routes/admin/products/delete-option.ts +++ b/packages/medusa/src/api/routes/admin/products/delete-option.ts @@ -24,7 +24,7 @@ import { ProductService } from "../../../../services" * medusa.admin.products.deleteOption(productId, optionId) * .then(({ option_id, object, deleted, product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/delete-product.ts b/packages/medusa/src/api/routes/admin/products/delete-product.ts index 9329b35ef3..5c7cf6cbe3 100644 --- a/packages/medusa/src/api/routes/admin/products/delete-product.ts +++ b/packages/medusa/src/api/routes/admin/products/delete-product.ts @@ -21,7 +21,7 @@ import { ProductService } from "../../../../services" * medusa.admin.products.delete(productId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/delete-variant.ts b/packages/medusa/src/api/routes/admin/products/delete-variant.ts index f3f42ad99c..472aaa016a 100644 --- a/packages/medusa/src/api/routes/admin/products/delete-variant.ts +++ b/packages/medusa/src/api/routes/admin/products/delete-variant.ts @@ -28,7 +28,7 @@ import { EntityManager } from "typeorm" * medusa.admin.products.deleteVariant(productId, variantId) * .then(({ variant_id, object, deleted, product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/get-product.ts b/packages/medusa/src/api/routes/admin/products/get-product.ts index 7d3d00cda3..f08f9a3b52 100644 --- a/packages/medusa/src/api/routes/admin/products/get-product.ts +++ b/packages/medusa/src/api/routes/admin/products/get-product.ts @@ -30,7 +30,7 @@ import { defaultAdminProductRemoteQueryObject } from "./index" * medusa.admin.products.retrieve(productId) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/index.ts b/packages/medusa/src/api/routes/admin/products/index.ts index 11777b5991..68391429b6 100644 --- a/packages/medusa/src/api/routes/admin/products/index.ts +++ b/packages/medusa/src/api/routes/admin/products/index.ts @@ -231,6 +231,7 @@ export const defaultAdminProductRemoteQueryObject = { /** * @schema AdminProductsDeleteOptionRes * type: object + * description: "The details of deleting a product's option." * x-expanded-relations: * field: product * relations: @@ -273,6 +274,7 @@ export type AdminProductsDeleteOptionRes = { /** * @schema AdminProductsDeleteVariantRes * type: object + * description: "The details of deleting a product's variant." * x-expanded-relations: * field: product * relations: @@ -315,6 +317,7 @@ export type AdminProductsDeleteVariantRes = { /** * @schema AdminProductsDeleteRes * type: object + * description: "The details of deleting a product." * required: * - id * - object @@ -341,6 +344,7 @@ export type AdminProductsDeleteRes = { /** * @schema AdminProductsListRes * type: object + * description: "The list of products with pagination fields." * x-expanded-relations: * field: products * relations: @@ -426,6 +430,7 @@ export type AdminProductsListTypesRes = { /** * @schema AdminProductsListTagsRes * type: object + * description: "The usage details of product tags." * required: * - tags * properties: @@ -460,6 +465,7 @@ export type AdminProductsListTagsRes = { /** * @schema AdminProductsRes * type: object + * description: "The product's details." * x-expanded-relations: * field: product * relations: diff --git a/packages/medusa/src/api/routes/admin/products/list-products.ts b/packages/medusa/src/api/routes/admin/products/list-products.ts index e81a8f9a33..fdd596d312 100644 --- a/packages/medusa/src/api/routes/admin/products/list-products.ts +++ b/packages/medusa/src/api/routes/admin/products/list-products.ts @@ -199,7 +199,7 @@ import { promiseAll } from "@medusajs/utils" * medusa.admin.products.list() * .then(({ products, limit, offset, count }) => { * console.log(products.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -414,25 +414,45 @@ async function listAndCountProductWithIsolatedProductModule( return [products, count] } +/** + * Parameters used to filter and configure the pagination of the retrieved products. + */ export class AdminGetProductsParams extends FilterableProductProps { + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset?: number = 0 + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsNumber() @IsOptional() @Type(() => Number) limit?: number = 50 + /** + * {@inheritDoc FindParams.expand} + */ @IsString() @IsOptional() expand?: string + /** + * {@inheritDoc FindParams.fields} + */ @IsString() @IsOptional() fields?: string + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string diff --git a/packages/medusa/src/api/routes/admin/products/list-tag-usage-count.ts b/packages/medusa/src/api/routes/admin/products/list-tag-usage-count.ts index dc9c6cd07d..0145f15b0b 100644 --- a/packages/medusa/src/api/routes/admin/products/list-tag-usage-count.ts +++ b/packages/medusa/src/api/routes/admin/products/list-tag-usage-count.ts @@ -18,7 +18,7 @@ import { ProductService } from "../../../../services" * medusa.admin.products.listTags() * .then(({ tags }) => { * console.log(tags.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/list-types.ts b/packages/medusa/src/api/routes/admin/products/list-types.ts index 144ae38202..42d8778c7f 100644 --- a/packages/medusa/src/api/routes/admin/products/list-types.ts +++ b/packages/medusa/src/api/routes/admin/products/list-types.ts @@ -19,7 +19,7 @@ import { ProductService } from "../../../../services" * medusa.admin.products.listTypes() * .then(({ types }) => { * console.log(types.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/set-metadata.ts b/packages/medusa/src/api/routes/admin/products/set-metadata.ts index 641de61345..e99554bf34 100644 --- a/packages/medusa/src/api/routes/admin/products/set-metadata.ts +++ b/packages/medusa/src/api/routes/admin/products/set-metadata.ts @@ -36,7 +36,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/update-option.ts b/packages/medusa/src/api/routes/admin/products/update-option.ts index 08277e0c0c..1d11c49679 100644 --- a/packages/medusa/src/api/routes/admin/products/update-option.ts +++ b/packages/medusa/src/api/routes/admin/products/update-option.ts @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/products/update-product.ts b/packages/medusa/src/api/routes/admin/products/update-product.ts index 501add5c5c..d942fd08a6 100644 --- a/packages/medusa/src/api/routes/admin/products/update-product.ts +++ b/packages/medusa/src/api/routes/admin/products/update-product.ts @@ -81,7 +81,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -621,6 +621,9 @@ class ProductVariantReq { * width: * description: The width of the Product. * type: number + * hs_code: + * description: The Harmonized System code of the product variant. + * type: string * origin_country: * description: The country of origin of the Product. * type: string diff --git a/packages/medusa/src/api/routes/admin/products/update-variant.ts b/packages/medusa/src/api/routes/admin/products/update-variant.ts index a8e4c8ea93..9f706401d6 100644 --- a/packages/medusa/src/api/routes/admin/products/update-variant.ts +++ b/packages/medusa/src/api/routes/admin/products/update-variant.ts @@ -65,7 +65,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts index 2ee83d0ee4..250615b765 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts @@ -10,7 +10,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key" * @oas [post] /admin/publishable-api-keys/{id}/sales-channels/batch * operationId: "PostPublishableApiKeySalesChannelsChannelsBatch" * summary: "Add Sales Channels" - * description: "Assign a list of sales channels to a publishable API key." + * description: "Add a list of sales channels to a publishable API key." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Publishable Api Key. @@ -37,7 +37,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key" * }) * .then(({ publishable_api_key }) => { * console.log(publishable_api_key.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts index 10ce081118..f1a0ec38fa 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts @@ -8,7 +8,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key" * @oas [post] /admin/publishable-api-keys * operationId: "PostPublishableApiKeys" * summary: "Create Publishable API Key" - * description: "Creates a Publishable API Key." + * description: "Create a Publishable API Key." * requestBody: * content: * application/json: diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts index 40c234b0fd..8c0d201319 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts @@ -37,7 +37,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key" * }) * .then(({ publishable_api_key }) => { * console.log(publishable_api_key.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/index.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/index.ts index 092611b375..42de40524d 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/index.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/index.ts @@ -77,6 +77,7 @@ export default (app) => { /** * @schema AdminPublishableApiKeysRes * type: object + * description: "The publishable API key's details." * required: * - publishable_api_key * properties: @@ -91,6 +92,7 @@ export type AdminPublishableApiKeysRes = { /** * @schema AdminPublishableApiKeysListRes * type: object + * description: The list of publishable API keys with pagination fields. * required: * - publishable_api_keys * - count @@ -141,6 +143,7 @@ export type AdminPublishableApiKeyDeleteRes = DeleteResponse /** * @schema AdminPublishableApiKeysListSalesChannelsRes * type: object + * description: "The list of sales channel." * required: * - sales_channels * properties: diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts index 2e98b349ef..ab95214378 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts @@ -24,9 +24,9 @@ import { extendedFindParamsMixin } from "../../../../types/common" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.publishableApiKeys.listSalesChannels() - * .then(({ sales_channels }) => { - * console.log(sales_channels.length) - * }) + * .then(({ sales_channels }) => { + * console.log(sales_channels.length) + * }) * - lang: Shell * label: cURL * source: | @@ -75,7 +75,13 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter the sales channels. + */ export class GetPublishableApiKeySalesChannelsParams extends extendedFindParamsMixin() { + /** + * Search term to search sales channels' names and descriptions. + */ @IsOptional() @IsString() q?: string diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-keys.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-keys.ts index 49257cf88f..37a7a09a28 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-keys.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-keys.ts @@ -27,9 +27,9 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.publishableApiKeys.list() - * .then(({ publishable_api_keys, count, limit, offset }) => { - * console.log(publishable_api_keys) - * }) + * .then(({ publishable_api_keys, count, limit, offset }) => { + * console.log(publishable_api_keys) + * }) * - lang: Shell * label: cURL * source: | @@ -82,10 +82,16 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved publishable API keys. + */ export class GetPublishableApiKeysParams extends extendedFindParamsMixin({ limit: 20, offset: 0, }) { + /** + * Search term to search publishable API keys' titles. + */ @IsString() @IsOptional() q?: string diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts index c245600667..ece3524f38 100644 --- a/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts +++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts @@ -21,9 +21,9 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.admin.publishableApiKeys.revoke(publishableApiKeyId) - * .then(({ publishable_api_key }) => { - * console.log(publishable_api_key.id) - * }) + * .then(({ publishable_api_key }) => { + * console.log(publishable_api_key.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/add-country.ts b/packages/medusa/src/api/routes/admin/regions/add-country.ts index 0c9dea2140..3344599f57 100644 --- a/packages/medusa/src/api/routes/admin/regions/add-country.ts +++ b/packages/medusa/src/api/routes/admin/regions/add-country.ts @@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator" * @oas [post] /admin/regions/{id}/countries * operationId: "PostRegionsRegionCountries" * summary: "Add Country" - * description: "Add a Country to the list of Countries in a Region" + * description: "Add a Country to the list of Countries in a Region." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Region. @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts b/packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts index 864ba49456..33a1e469a2 100644 --- a/packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts +++ b/packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts b/packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts index e022dd7389..9e8993aa9a 100644 --- a/packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts +++ b/packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts @@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/create-region.ts b/packages/medusa/src/api/routes/admin/regions/create-region.ts index dc5edf7e88..95e2013001 100644 --- a/packages/medusa/src/api/routes/admin/regions/create-region.ts +++ b/packages/medusa/src/api/routes/admin/regions/create-region.ts @@ -50,7 +50,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/delete-region.ts b/packages/medusa/src/api/routes/admin/regions/delete-region.ts index c15f7ca602..8b486117c5 100644 --- a/packages/medusa/src/api/routes/admin/regions/delete-region.ts +++ b/packages/medusa/src/api/routes/admin/regions/delete-region.ts @@ -21,7 +21,7 @@ import RegionService from "../../../../services/region" * medusa.admin.regions.delete(regionId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/get-fulfillment-options.ts b/packages/medusa/src/api/routes/admin/regions/get-fulfillment-options.ts index 9b6c444bcf..822e7241a2 100644 --- a/packages/medusa/src/api/routes/admin/regions/get-fulfillment-options.ts +++ b/packages/medusa/src/api/routes/admin/regions/get-fulfillment-options.ts @@ -22,7 +22,7 @@ import RegionService from "../../../../services/region" * medusa.admin.regions.retrieveFulfillmentOptions(regionId) * .then(({ fulfillment_options }) => { * console.log(fulfillment_options.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/get-region.ts b/packages/medusa/src/api/routes/admin/regions/get-region.ts index ae33b8132a..f0709b8fba 100644 --- a/packages/medusa/src/api/routes/admin/regions/get-region.ts +++ b/packages/medusa/src/api/routes/admin/regions/get-region.ts @@ -22,7 +22,7 @@ import RegionService from "../../../../services/region" * medusa.admin.regions.retrieve(regionId) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/index.ts b/packages/medusa/src/api/routes/admin/regions/index.ts index ee10d5ab27..767d759fe8 100644 --- a/packages/medusa/src/api/routes/admin/regions/index.ts +++ b/packages/medusa/src/api/routes/admin/regions/index.ts @@ -88,6 +88,7 @@ export const defaultAdminRegionRelations = [ /** * @schema AdminRegionsRes * type: object + * description: "The region's details." * x-expanded-relations: * field: region * relations: @@ -104,13 +105,14 @@ export const defaultAdminRegionRelations = [ * description: "Region details." * $ref: "#/components/schemas/Region" */ -export class AdminRegionsRes { +export type AdminRegionsRes = { region: Region } /** * @schema AdminRegionsListRes * type: object + * description: "The list of regions with pagination fields." * x-expanded-relations: * field: regions * relations: @@ -175,6 +177,7 @@ export class FulfillmentOption { /** * @schema AdminGetRegionsRegionFulfillmentOptionsRes * type: object + * description: "The list of fulfillment options in a region." * required: * - fulfillment_options * properties: @@ -210,4 +213,3 @@ export * from "./add-payment-provider" export * from "./create-region" export * from "./list-regions" export * from "./update-region" - diff --git a/packages/medusa/src/api/routes/admin/regions/list-regions.ts b/packages/medusa/src/api/routes/admin/regions/list-regions.ts index 81e32fa1bb..b0f09fc747 100644 --- a/packages/medusa/src/api/routes/admin/regions/list-regions.ts +++ b/packages/medusa/src/api/routes/admin/regions/list-regions.ts @@ -12,7 +12,7 @@ import { validator } from "../../../../utils/validator" * @oas [get] /admin/regions * operationId: "GetRegions" * summary: "List Regions" - * description: "Retrieve a list of Regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated" + * description: "Retrieve a list of Regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated." * x-authenticated: true * parameters: * - in: query @@ -111,7 +111,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.regions.list() * .then(({ regions, limit, offset, count }) => { * console.log(regions.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -170,29 +170,52 @@ export default async (req, res) => { }) } +/** + * {@inheritDoc FindPaginationParams} + */ export class AdminGetRegionsPaginationParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsInt() @IsOptional() @Type(() => Number) limit?: number = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsInt() @IsOptional() @Type(() => Number) offset?: number = 0 } +/** + * Parameters used to filter and configure the pagination of the retrieved regions. + */ export class AdminGetRegionsParams extends AdminGetRegionsPaginationParams { + /** + * Date filters to apply on the regions' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the regions' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the regions' `deleted_at` date. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/api/routes/admin/regions/remove-country.ts b/packages/medusa/src/api/routes/admin/regions/remove-country.ts index 95bb1428ec..1175d5d52a 100644 --- a/packages/medusa/src/api/routes/admin/regions/remove-country.ts +++ b/packages/medusa/src/api/routes/admin/regions/remove-country.ts @@ -32,7 +32,7 @@ import RegionService from "../../../../services/region" * medusa.admin.regions.deleteCountry(regionId, "dk") * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/remove-fulfillment-provider.ts b/packages/medusa/src/api/routes/admin/regions/remove-fulfillment-provider.ts index ce93857158..36d25cc533 100644 --- a/packages/medusa/src/api/routes/admin/regions/remove-fulfillment-provider.ts +++ b/packages/medusa/src/api/routes/admin/regions/remove-fulfillment-provider.ts @@ -24,7 +24,7 @@ import RegionService from "../../../../services/region" * medusa.admin.regions.deleteFulfillmentProvider(regionId, "manual") * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/remove-payment-provider.ts b/packages/medusa/src/api/routes/admin/regions/remove-payment-provider.ts index 9c6522fea8..8dd6e28b26 100644 --- a/packages/medusa/src/api/routes/admin/regions/remove-payment-provider.ts +++ b/packages/medusa/src/api/routes/admin/regions/remove-payment-provider.ts @@ -24,7 +24,7 @@ import RegionService from "../../../../services/region" * medusa.admin.regions.deletePaymentProvider(regionId, "manual") * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/regions/update-region.ts b/packages/medusa/src/api/routes/admin/regions/update-region.ts index 59eba0ed3a..f49531b534 100644 --- a/packages/medusa/src/api/routes/admin/regions/update-region.ts +++ b/packages/medusa/src/api/routes/admin/regions/update-region.ts @@ -41,7 +41,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -111,13 +111,15 @@ export default async (req, res) => { * url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes * description: See a list of codes. * automatic_taxes: - * description: "If set to `true`, the Medusa backend will automatically calculate taxes for carts in this region. If set to `false`, the taxes must be calculated manually." + * description: >- + * If set to `true`, the Medusa backend will automatically calculate taxes for carts in this region. If set to `false`, the taxes must be calculated manually. * externalDocs: * url: https://docs.medusajs.com/modules/taxes/storefront/manual-calculation * description: How to calculate taxes in a storefront. * type: boolean * gift_cards_taxable: - * description: "If set to `true`, taxes will be applied on gift cards." + * description: >- + * If set to `true`, taxes will be applied on gift cards. * type: boolean * tax_provider_id: * description: "The ID of the tax provider to use. If none provided, the system tax provider is used." diff --git a/packages/medusa/src/api/routes/admin/reservations/create-reservation.ts b/packages/medusa/src/api/routes/admin/reservations/create-reservation.ts index efcb9ab55e..67e3971838 100644 --- a/packages/medusa/src/api/routes/admin/reservations/create-reservation.ts +++ b/packages/medusa/src/api/routes/admin/reservations/create-reservation.ts @@ -30,7 +30,7 @@ import { validateUpdateReservationQuantity } from "./utils/validate-reservation- * }) * .then(({ reservation }) => { * console.log(reservation.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -116,6 +116,9 @@ export default async (req, res) => { * quantity: * description: "The quantity to reserve." * type: number + * description: + * description: "The reservation's description." + * type: string * metadata: * description: An optional set of key-value pairs with additional information. * type: object diff --git a/packages/medusa/src/api/routes/admin/reservations/delete-reservation.ts b/packages/medusa/src/api/routes/admin/reservations/delete-reservation.ts index 080464e5ce..6d919ce561 100644 --- a/packages/medusa/src/api/routes/admin/reservations/delete-reservation.ts +++ b/packages/medusa/src/api/routes/admin/reservations/delete-reservation.ts @@ -21,7 +21,7 @@ import { EntityManager } from "typeorm" * medusa.admin.reservations.delete(reservationId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/reservations/get-reservation.ts b/packages/medusa/src/api/routes/admin/reservations/get-reservation.ts index c957891ede..68738ee05f 100644 --- a/packages/medusa/src/api/routes/admin/reservations/get-reservation.ts +++ b/packages/medusa/src/api/routes/admin/reservations/get-reservation.ts @@ -5,7 +5,7 @@ import { MedusaError } from "@medusajs/utils" * @oas [get] /admin/reservations/{id} * operationId: "GetReservationsReservation" * summary: "Get a Reservation" - * description: "Retrieve a reservation's details.'" + * description: "Retrieve a reservation's details." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the reservation. @@ -19,7 +19,7 @@ import { MedusaError } from "@medusajs/utils" * medusa.admin.reservations.retrieve(reservationId) * .then(({ reservation }) => { * console.log(reservation.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/reservations/index.ts b/packages/medusa/src/api/routes/admin/reservations/index.ts index bf49b75de4..d72a0fe537 100644 --- a/packages/medusa/src/api/routes/admin/reservations/index.ts +++ b/packages/medusa/src/api/routes/admin/reservations/index.ts @@ -59,6 +59,7 @@ export default (app) => { /** * @schema AdminReservationsRes * type: object + * description: "The reservation's details." * required: * - reservation * properties: @@ -92,6 +93,7 @@ export type ExtendedReservationItem = ReservationItemDTO & { /** * @schema AdminReservationsListRes * type: object + * description: "The list of reservations with pagination fields." * required: * - reservations * - count diff --git a/packages/medusa/src/api/routes/admin/reservations/list-reservations.ts b/packages/medusa/src/api/routes/admin/reservations/list-reservations.ts index 0f932b57cd..3facc9a92c 100644 --- a/packages/medusa/src/api/routes/admin/reservations/list-reservations.ts +++ b/packages/medusa/src/api/routes/admin/reservations/list-reservations.ts @@ -206,39 +206,63 @@ export default async (req: Request, res: Response) => { res.json({ reservations, count, limit, offset }) } +/** + * Parameters used to filter and configure the pagination of the retrieved reservations. + */ export class AdminGetReservationsParams extends extendedFindParamsMixin({ limit: 20, offset: 0, }) { + /** + * Location IDs to filter reservations by. + */ @IsOptional() @IsType([String, [String]]) location_id?: string | string[] + /** + * Inventory item IDs to filter reservations by. + */ @IsArray() @IsString({ each: true }) @IsOptional() inventory_item_id?: string[] + /** + * Line item IDs to filter reservations by. + */ @IsArray() @IsString({ each: true }) @IsOptional() line_item_id?: string[] + /** + * "Create by" user IDs to filter reservations by. + */ @IsArray() @IsString({ each: true }) @IsOptional() created_by?: string[] + /** + * Numerical filters to apply on the reservations' `quantity` field. + */ @IsOptional() @ValidateNested() @Type(() => NumericalComparisonOperator) quantity?: NumericalComparisonOperator + /** + * Date filters to apply on the reservations' `created_at` field. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * String filters tp apply on the reservations' `description` field. + */ @IsOptional() @IsType([StringComparisonOperator, String]) description?: string | StringComparisonOperator diff --git a/packages/medusa/src/api/routes/admin/reservations/update-reservation.ts b/packages/medusa/src/api/routes/admin/reservations/update-reservation.ts index 935b198166..5d624c19a6 100644 --- a/packages/medusa/src/api/routes/admin/reservations/update-reservation.ts +++ b/packages/medusa/src/api/routes/admin/reservations/update-reservation.ts @@ -10,7 +10,7 @@ import { validateUpdateReservationQuantity } from "./utils/validate-reservation- * @oas [post] /admin/reservations/{id} * operationId: "PostReservationsReservation" * summary: "Update a Reservation" - * description: "Update a Reservation's details.'" + * description: "Update a Reservation's details." * x-authenticated: true * parameters: * - (path) id=* {string} The ID of the Reservation. @@ -31,7 +31,7 @@ import { validateUpdateReservationQuantity } from "./utils/validate-reservation- * }) * .then(({ reservation }) => { * console.log(reservation.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -109,6 +109,9 @@ export default async (req, res) => { * quantity: * description: "The quantity to reserve." * type: number + * description: + * description: "The reservation's description." + * type: string * metadata: * description: An optional set of key-value pairs with additional information. * type: object diff --git a/packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts b/packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts index 46a1fde75f..b5a35ad4b0 100644 --- a/packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts +++ b/packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts @@ -34,7 +34,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ return_reason }) => { * console.log(return_reason.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/return-reasons/delete-reason.ts b/packages/medusa/src/api/routes/admin/return-reasons/delete-reason.ts index 8b1194d716..0998abdad9 100644 --- a/packages/medusa/src/api/routes/admin/return-reasons/delete-reason.ts +++ b/packages/medusa/src/api/routes/admin/return-reasons/delete-reason.ts @@ -21,7 +21,7 @@ import { ReturnReasonService } from "../../../../services" * medusa.admin.returnReasons.delete(returnReasonId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/return-reasons/get-reason.ts b/packages/medusa/src/api/routes/admin/return-reasons/get-reason.ts index edeef8ed98..e16509fd69 100644 --- a/packages/medusa/src/api/routes/admin/return-reasons/get-reason.ts +++ b/packages/medusa/src/api/routes/admin/return-reasons/get-reason.ts @@ -25,7 +25,7 @@ import { ReturnReasonService } from "../../../../services" * medusa.admin.returnReasons.retrieve(returnReasonId) * .then(({ return_reason }) => { * console.log(return_reason.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/return-reasons/index.ts b/packages/medusa/src/api/routes/admin/return-reasons/index.ts index 630b03244e..fc36e65ad0 100644 --- a/packages/medusa/src/api/routes/admin/return-reasons/index.ts +++ b/packages/medusa/src/api/routes/admin/return-reasons/index.ts @@ -55,6 +55,7 @@ export const defaultAdminReturnReasonsRelations: (keyof ReturnReason)[] = [ /** * @schema AdminReturnReasonsRes * type: object + * description: "The return reason's details." * x-expanded-relations: * field: return_reason * relations: @@ -64,6 +65,7 @@ export const defaultAdminReturnReasonsRelations: (keyof ReturnReason)[] = [ * - return_reason * properties: * return_reason: + * description: "The return reason's details." * $ref: "#/components/schemas/ReturnReason" */ export type AdminReturnReasonsRes = { @@ -73,6 +75,7 @@ export type AdminReturnReasonsRes = { /** * @schema AdminReturnReasonsListRes * type: object + * description: "The list of return reasons." * x-expanded-relations: * field: return_reasons * relations: @@ -83,6 +86,7 @@ export type AdminReturnReasonsRes = { * properties: * return_reasons: * type: array + * description: "The list of return reasons." * items: * $ref: "#/components/schemas/ReturnReason" */ diff --git a/packages/medusa/src/api/routes/admin/return-reasons/list-reasons.ts b/packages/medusa/src/api/routes/admin/return-reasons/list-reasons.ts index 3c024682cd..b8b3cad429 100644 --- a/packages/medusa/src/api/routes/admin/return-reasons/list-reasons.ts +++ b/packages/medusa/src/api/routes/admin/return-reasons/list-reasons.ts @@ -24,7 +24,7 @@ import { Selector } from "../../../../types/common" * medusa.admin.returnReasons.list() * .then(({ return_reasons }) => { * console.log(return_reasons.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts b/packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts index 70b2a09569..526b9e12a9 100644 --- a/packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts +++ b/packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts @@ -35,7 +35,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ return_reason }) => { * console.log(return_reason.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/returns/cancel-return.ts b/packages/medusa/src/api/routes/admin/returns/cancel-return.ts index 6c8d7d4976..24f3231968 100644 --- a/packages/medusa/src/api/routes/admin/returns/cancel-return.ts +++ b/packages/medusa/src/api/routes/admin/returns/cancel-return.ts @@ -20,8 +20,8 @@ import { defaultReturnCancelFields, defaultReturnCancelRelations } from "." * // must be previously logged in or use api token * medusa.admin.returns.cancel(returnId) * .then(({ order }) => { - * console.log(order.id); - * }); + * console.log(order.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/returns/index.ts b/packages/medusa/src/api/routes/admin/returns/index.ts index b149320201..6a4f84a688 100644 --- a/packages/medusa/src/api/routes/admin/returns/index.ts +++ b/packages/medusa/src/api/routes/admin/returns/index.ts @@ -39,6 +39,7 @@ export const defaultReturnCancelFields = [...defaultAdminOrdersFields] /** * @schema AdminReturnsCancelRes * type: object + * description: "The associated order's details." * x-expanded-relations: * field: order * relations: @@ -101,6 +102,7 @@ export type AdminReturnsCancelRes = { /** * @schema AdminReturnsListRes * type: object + * description: "The list of returns with pagination fields." * x-expanded-relation: * field: returns * relations: @@ -134,6 +136,7 @@ export type AdminReturnsListRes = PaginatedResponse & { /** * @schema AdminReturnsRes * type: object + * description: "The return's details." * x-expanded-relation: * field: return * relations: diff --git a/packages/medusa/src/api/routes/admin/returns/list-returns.ts b/packages/medusa/src/api/routes/admin/returns/list-returns.ts index 5c6f1c6ea8..2e7dc6aa73 100644 --- a/packages/medusa/src/api/routes/admin/returns/list-returns.ts +++ b/packages/medusa/src/api/routes/admin/returns/list-returns.ts @@ -27,8 +27,8 @@ import { validator } from "../../../../utils/validator" * // must be previously logged in or use api token * medusa.admin.returns.list() * .then(({ returns, limit, offset, count }) => { - * console.log(returns.length); - * }); + * console.log(returns.length) + * }) * - lang: Shell * label: cURL * source: | @@ -86,12 +86,23 @@ export default async (req, res) => { }) } +/** + * {@inheritDoc FindPaginationParams} + */ export class AdminGetReturnsParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsOptional() @IsNumber() @Type(() => Number) limit?: number = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 50 + */ @IsOptional() @IsNumber() @Type(() => Number) diff --git a/packages/medusa/src/api/routes/admin/returns/receive-return.ts b/packages/medusa/src/api/routes/admin/returns/receive-return.ts index f7572be199..9fb0bc6ed2 100644 --- a/packages/medusa/src/api/routes/admin/returns/receive-return.ts +++ b/packages/medusa/src/api/routes/admin/returns/receive-return.ts @@ -44,7 +44,7 @@ import { defaultRelations } from "." * }) * .then((data) => { * console.log(data.return.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -165,6 +165,9 @@ class Item { * refund: * description: The amount to refund. * type: number + * location_id: + * description: The ID of the location to return items from. + * type: string */ export class AdminPostReturnsReturnReceiveReq { @IsArray() diff --git a/packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts b/packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts index f04789cbce..72f5266495 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts @@ -37,7 +37,7 @@ import { Type } from "class-transformer" * }) * .then(({ sales_channel }) => { * console.log(sales_channel.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/associate-stock-location.ts b/packages/medusa/src/api/routes/admin/sales-channels/associate-stock-location.ts index 3a6662003a..23568f496b 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/associate-stock-location.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/associate-stock-location.ts @@ -34,7 +34,7 @@ import { * }) * .then(({ sales_channel }) => { * console.log(sales_channel.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts b/packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts index 3a2add3d69..7206822fd8 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts @@ -31,7 +31,7 @@ import SalesChannelService from "../../../../services/sales-channel" * }) * .then(({ sales_channel }) => { * console.log(sales_channel.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts b/packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts index 9877adf114..f261d45e9f 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts @@ -36,8 +36,8 @@ import { Type } from "class-transformer" * ] * }) * .then(({ sales_channel }) => { - * console.log(sales_channel.id); - * }); + * console.log(sales_channel.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/delete-sales-channel.ts b/packages/medusa/src/api/routes/admin/sales-channels/delete-sales-channel.ts index 32eb2b92f4..fdad2a8c89 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/delete-sales-channel.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/delete-sales-channel.ts @@ -22,8 +22,8 @@ import { SalesChannelService } from "../../../../services/" * // must be previously logged in or use api token * medusa.admin.salesChannels.delete(salesChannelId) * .then(({ id, object, deleted }) => { - * console.log(id); - * }); + * console.log(id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/get-sales-channel.ts b/packages/medusa/src/api/routes/admin/sales-channels/get-sales-channel.ts index a49f703e9f..13fcedeaae 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/get-sales-channel.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/get-sales-channel.ts @@ -22,7 +22,7 @@ import { SalesChannelService } from "../../../../services" * medusa.admin.salesChannels.retrieve(salesChannelId) * .then(({ sales_channel }) => { * console.log(sales_channel.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/index.ts b/packages/medusa/src/api/routes/admin/sales-channels/index.ts index 3aab522bb7..f574b82b71 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/index.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/index.ts @@ -88,6 +88,7 @@ export default (app) => { /** * @schema AdminSalesChannelsRes * type: object + * description: "The sales channel's details." * required: * - sales_channel * properties: @@ -146,6 +147,7 @@ export type AdminSalesChannelsDeleteLocationRes = DeleteResponse /** * @schema AdminSalesChannelsListRes * type: object + * description: "The list of sales channels with pagination fields." * required: * - sales_channels * - count diff --git a/packages/medusa/src/api/routes/admin/sales-channels/list-sales-channels.ts b/packages/medusa/src/api/routes/admin/sales-channels/list-sales-channels.ts index d4de02d825..e392175a5a 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/list-sales-channels.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/list-sales-channels.ts @@ -102,8 +102,8 @@ import { Type } from "class-transformer" * // must be previously logged in or use api token * medusa.admin.salesChannels.list() * .then(({ sales_channels, limit, offset, count }) => { - * console.log(sales_channels.length); - * }); + * console.log(sales_channels.length) + * }) * - lang: Shell * label: cURL * source: | @@ -156,38 +156,65 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved sales channels. + */ export class AdminGetSalesChannelsParams extends extendedFindParamsMixin() { + /** + * ID to filter sales channels by. + */ @IsString() @IsOptional() id?: string + /** + * Search term to search sales channels' names and descriptions. + */ @IsOptional() @IsString() q?: string + /** + * Name to filter sales channels by. + */ @IsOptional() @IsString() name?: string + /** + * Description to filter sales channels by. + */ @IsOptional() @IsString() description?: string + /** + * Date filters to apply on sales channels' `created_at` field. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on sales channels' `updated_at` field. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on sales channels' `deleted_at` field. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) deleted_at?: DateComparisonOperator + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string diff --git a/packages/medusa/src/api/routes/admin/sales-channels/remove-stock-location.ts b/packages/medusa/src/api/routes/admin/sales-channels/remove-stock-location.ts index 131bd419a3..a8182cb9fc 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/remove-stock-location.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/remove-stock-location.ts @@ -31,7 +31,7 @@ import { SalesChannelLocationService } from "../../../../services" * }) * .then(({ sales_channel }) => { * console.log(sales_channel.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/sales-channels/update-sales-channel.ts b/packages/medusa/src/api/routes/admin/sales-channels/update-sales-channel.ts index 04cc1ff7c3..237b670479 100644 --- a/packages/medusa/src/api/routes/admin/sales-channels/update-sales-channel.ts +++ b/packages/medusa/src/api/routes/admin/sales-channels/update-sales-channel.ts @@ -31,7 +31,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ sales_channel }) => { * console.log(sales_channel.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts index ab50af3e48..cfceed2a65 100644 --- a/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts +++ b/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts @@ -45,7 +45,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ shipping_option }) => { * console.log(shipping_option.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -145,13 +145,15 @@ class OptionRequirement { * description: "The data needed for the Fulfillment Provider to handle shipping with this Shipping Option." * type: object * price_type: - * description: "The type of the Shipping Option price. `flat_rate` indicates fixed pricing, whereas `calculated` indicates that the price will be calculated each time by the fulfillment provider." + * description: >- + * The type of the Shipping Option price. `flat_rate` indicates fixed pricing, whereas `calculated` indicates that the price will be calculated each time by the fulfillment provider. * type: string * enum: * - flat_rate * - calculated * amount: - * description: "The amount to charge for the Shipping Option. If the `price_type` is set to `calculated`, this amount will not actually be used." + * description: >- + * The amount to charge for the Shipping Option. If the `price_type` is set to `calculated`, this amount will not actually be used. * type: integer * requirements: * description: "The requirements that must be satisfied for the Shipping Option to be available." @@ -176,7 +178,8 @@ class OptionRequirement { * type: boolean * default: false * admin_only: - * description: If set to `true`, the shipping option can only be used when creating draft orders. + * description: >- + * If set to `true`, the shipping option can only be used when creating draft orders. * type: boolean * default: false * metadata: diff --git a/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts index a1eabb0408..442b5f68e4 100644 --- a/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts +++ b/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts @@ -20,7 +20,7 @@ import { EntityManager } from "typeorm" * medusa.admin.shippingOptions.delete(optionId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts index 29d12a692c..9764fbc475 100644 --- a/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts +++ b/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts @@ -20,7 +20,7 @@ import { defaultFields, defaultRelations } from "." * medusa.admin.shippingOptions.retrieve(optionId) * .then(({ shipping_option }) => { * console.log(shipping_option.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/shipping-options/index.ts b/packages/medusa/src/api/routes/admin/shipping-options/index.ts index 432ce3457f..7ef8a94a06 100644 --- a/packages/medusa/src/api/routes/admin/shipping-options/index.ts +++ b/packages/medusa/src/api/routes/admin/shipping-options/index.ts @@ -55,6 +55,7 @@ export const defaultRelations = ["region", "profile", "requirements"] /** * @schema AdminShippingOptionsListRes * type: object + * description: "The list of shipping options with pagination fields." * x-expanded-relations: * field: shipping_options * relations: @@ -92,6 +93,7 @@ export type AdminShippingOptionsListRes = PaginatedResponse & { /** * @schema AdminShippingOptionsRes * type: object + * description: "The shipping option's details." * x-expanded-relations: * field: shipping_option * relations: @@ -139,4 +141,3 @@ export * from "./delete-shipping-option" export * from "./get-shipping-option" export * from "./list-shipping-options" export * from "./update-shipping-option" - diff --git a/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts b/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts index 91ad812256..4d18935efb 100644 --- a/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts +++ b/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts @@ -41,7 +41,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.shippingOptions.list() * .then(({ shipping_options, count }) => { * console.log(shipping_options.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -91,16 +91,28 @@ export default async (req, res) => { res.status(200).json({ shipping_options: options, count }) } +/** + * Parameters used to filter the retrieved shipping options. + */ export class AdminGetShippingOptionsParams { + /** + * Filter shipping options by the ID of the region they belong to. + */ @IsOptional() @IsString() region_id?: string + /** + * Filter shipping options by whether they're return shipping options. + */ @IsOptional() @IsBoolean() @Transform(({ value }) => optionalBooleanMapper.get(value)) is_return?: boolean + /** + * Filter shipping options by whether they're available for admin users only. + */ @IsOptional() @IsBoolean() @Transform(({ value }) => optionalBooleanMapper.get(value)) diff --git a/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts index 4f3d164eb4..c42049e9da 100644 --- a/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts +++ b/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts @@ -51,7 +51,7 @@ import { UpdateShippingOptionInput } from "../../../../types/shipping-options" * }) * .then(({ shipping_option }) => { * console.log(shipping_option.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -139,10 +139,12 @@ class OptionRequirement { * description: "The name of the Shipping Option" * type: string * amount: - * description: "The amount to charge for the Shipping Option. If the `price_type` of the shipping option is `calculated`, this amount will not actually be used." + * description: >- + * The amount to charge for the Shipping Option. If the `price_type` of the shipping option is `calculated`, this amount will not actually be used. * type: integer * admin_only: - * description: If set to `true`, the shipping option can only be used when creating draft orders. + * description: >- + * If set to `true`, the shipping option can only be used when creating draft orders. * type: boolean * metadata: * description: "An optional set of key-value pairs with additional information." diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts index 1f6c7d83b4..9a102ae3db 100644 --- a/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts +++ b/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts @@ -29,7 +29,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ shipping_profile }) => { * console.log(shipping_profile.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -95,6 +95,12 @@ export default async (req, res) => { * description: The type of the Shipping Profile * type: string * enum: [default, gift_card, custom] + * metadata: + * description: An optional set of key-value pairs with additional information. + * type: object + * externalDocs: + * description: "Learn about the metadata attribute, and how to delete and update it." + * url: "https://docs.medusajs.com/development/entities/overview#metadata-attribute" */ export class AdminPostShippingProfilesReq { @IsString() diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts index 1cfe52a90c..d665c0f624 100644 --- a/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts +++ b/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts @@ -21,7 +21,7 @@ import { ShippingProfileService } from "../../../../services" * medusa.admin.shippingProfiles.delete(profileId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts index 231f967e6c..db286f44c4 100644 --- a/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts +++ b/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts @@ -25,7 +25,7 @@ import { ShippingProfileService } from "../../../../services" * medusa.admin.shippingProfiles.retrieve(profileId) * .then(({ shipping_profile }) => { * console.log(shipping_profile.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts index f20763e481..6c7fd99636 100644 --- a/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts +++ b/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts @@ -71,6 +71,7 @@ export type AdminDeleteShippingProfileRes = DeleteResponse /** * @schema AdminShippingProfilesRes * type: object + * description: "The shipping profile's details." * x-expanded-relations: * field: shipping_profile * relations: @@ -90,6 +91,7 @@ export type AdminShippingProfilesRes = { /** * @schema AdminShippingProfilesListRes * type: object + * description: "The list of shipping profiles." * required: * - shipping_profiles * properties: diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts index 8a4158bd6a..7df3653a4c 100644 --- a/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts +++ b/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts @@ -18,7 +18,7 @@ import { ShippingProfileService } from "../../../../services" * medusa.admin.shippingProfiles.list() * .then(({ shipping_profiles }) => { * console.log(shipping_profiles.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts index 49e082cae1..f7c1edcb71 100644 --- a/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts +++ b/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts @@ -41,7 +41,7 @@ import { * }) * .then(({ shipping_profile }) => { * console.log(shipping_profile.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts b/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts index 90d488c6a3..898006a899 100644 --- a/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts +++ b/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts @@ -39,7 +39,7 @@ import { IStockLocationService } from "@medusajs/types" * }) * .then(({ stock_location }) => { * console.log(stock_location.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -115,7 +115,7 @@ export default async (req: Request, res: Response) => { * description: Stock location address' city * example: Mexico city * country_code: - * description: "The 2 character ISO code for the country." + * description: "The two character ISO code for the country." * type: string * externalDocs: * url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements diff --git a/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts b/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts index 05afac8c6b..c4a456ed81 100644 --- a/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts +++ b/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts @@ -30,7 +30,7 @@ import { joinSalesChannels } from "./utils/join-sales-channels" * medusa.admin.stockLocations.retrieve(stockLocationId) * .then(({ stock_location }) => { * console.log(stock_location.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/stock-locations/index.ts b/packages/medusa/src/api/routes/admin/stock-locations/index.ts index 32ffe97fb4..7a55b359b3 100644 --- a/packages/medusa/src/api/routes/admin/stock-locations/index.ts +++ b/packages/medusa/src/api/routes/admin/stock-locations/index.ts @@ -112,6 +112,7 @@ export type AdminStockLocationsDeleteRes = DeleteResponse /** * @schema AdminStockLocationsRes * type: object + * description: "The stock location's details." * required: * - stock_location * properties: @@ -126,6 +127,7 @@ export type AdminStockLocationsRes = { /** * @schema AdminStockLocationsListRes * type: object + * description: "The list of stock locations with pagination fields." * required: * - stock_locations * - count diff --git a/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts b/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts index 8f2cfbd69f..cdb9e64d17 100644 --- a/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts +++ b/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts @@ -102,7 +102,7 @@ import { joinSalesChannels } from "./utils/join-sales-channels" * medusa.admin.stockLocations.list() * .then(({ stock_locations, limit, offset, count }) => { * console.log(stock_locations.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -192,22 +192,37 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved stock locations. + */ export class AdminGetStockLocationsParams extends extendedFindParamsMixin({ limit: 20, offset: 0, }) { + /** + * IDs to filter stock locations by. + */ @IsOptional() @IsType([String, [String]]) id?: string | string[] + /** + * Names to filter stock locations by. + */ @IsOptional() @IsType([String, [String]]) name?: string | string[] + /** + * Filter stock locations by the ID of their associated addresses. + */ @IsOptional() @IsType([String, [String]]) address_id?: string | string[] + /** + * Filter stock locations by the ID of their associated sales channels. + */ @IsOptional() @IsType([String, [String]]) sales_channel_id?: string | string[] diff --git a/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts b/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts index 365961c901..1ae42ee438 100644 --- a/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts +++ b/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts @@ -33,7 +33,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ stock_location }) => { * console.log(stock_location.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -86,33 +86,60 @@ export default async (req: Request, res: Response) => { res.status(200).json({ stock_location: stockLocation }) } +/** + * The attributes of a stock location address to create or update. + */ class StockLocationAddress { + /** + * First line address. + */ @IsString() address_1: string + /** + * Second line address. + */ @IsOptional() @IsString() address_2?: string + /** + * Company. + */ @IsOptional() @IsString() company?: string + /** + * City. + */ @IsOptional() @IsString() city?: string + /** + * Country code. + */ @IsString() country_code: string + /** + * Phone. + */ @IsOptional() @IsString() phone?: string + /** + * Postal code. + */ @IsOptional() @IsString() postal_code?: string + /** + * Province. + */ @IsOptional() @IsString() province?: string @@ -136,6 +163,7 @@ class StockLocationAddress { * description: "Learn about the metadata attribute, and how to delete and update it." * url: "https://docs.medusajs.com/development/entities/overview#metadata-attribute" * address: + * description: The data of an associated address to create or update. * $ref: "#/components/schemas/StockLocationAddressInput" */ export class AdminPostStockLocationsLocationReq { diff --git a/packages/medusa/src/api/routes/admin/store/add-currency.ts b/packages/medusa/src/api/routes/admin/store/add-currency.ts index 359487a362..a6a3f863de 100644 --- a/packages/medusa/src/api/routes/admin/store/add-currency.ts +++ b/packages/medusa/src/api/routes/admin/store/add-currency.ts @@ -5,7 +5,8 @@ import { EntityManager } from "typeorm" * @oas [post] /admin/store/currencies/{code} * operationId: "PostStoreCurrenciesCode" * summary: "Add a Currency Code" - * description: "Add a Currency Code to the available currencies in a store. This does not create new currencies, as currencies are defined within the Medusa backend. To create a currency, you can create a migration that inserts the currency into the database." + * description: "Add a Currency Code to the available currencies in a store. This does not create new currencies, as currencies are defined within the Medusa backend. + * To create a currency, you can create a migration that inserts the currency into the database." * x-authenticated: true * parameters: * - in: path @@ -29,7 +30,7 @@ import { EntityManager } from "typeorm" * medusa.admin.store.addCurrency("eur") * .then(({ store }) => { * console.log(store.currencies); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/store/get-store.ts b/packages/medusa/src/api/routes/admin/store/get-store.ts index 2ea3b28e75..f8cd768c91 100644 --- a/packages/medusa/src/api/routes/admin/store/get-store.ts +++ b/packages/medusa/src/api/routes/admin/store/get-store.ts @@ -26,7 +26,7 @@ import { MedusaModule } from "@medusajs/modules-sdk" * medusa.admin.store.retrieve() * .then(({ store }) => { * console.log(store.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/store/index.ts b/packages/medusa/src/api/routes/admin/store/index.ts index 316bf489a5..877a1852c8 100644 --- a/packages/medusa/src/api/routes/admin/store/index.ts +++ b/packages/medusa/src/api/routes/admin/store/index.ts @@ -35,6 +35,7 @@ export const defaultRelationsExtended = ["currencies", "default_currency"] /** * @schema AdminExtendedStoresRes * type: object + * description: "The store's details with additional details like payment and tax providers." * x-expanded-relations: * field: store * relations: @@ -54,6 +55,7 @@ export type AdminExtendedStoresRes = { /** * @schema AdminStoresRes * type: object + * description: "The store's details." * required: * - store * properties: @@ -68,6 +70,7 @@ export type AdminStoresRes = { /** * @schema AdminTaxProvidersList * type: object + * description: "The list of tax providers in a store." * required: * - tax_providers * properties: @@ -84,6 +87,7 @@ export type AdminTaxProvidersList = { /** * @schema AdminPaymentProvidersList * type: object + * description: "The list of payment providers in a store." * required: * - payment_providers * properties: diff --git a/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts b/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts index cebee2b84c..92e1128382 100644 --- a/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts +++ b/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts @@ -18,7 +18,7 @@ import { PaymentProviderService } from "../../../../services" * medusa.admin.store.listPaymentProviders() * .then(({ payment_providers }) => { * console.log(payment_providers.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts b/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts index 7a568e559c..fac54b82d8 100644 --- a/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts +++ b/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts @@ -18,7 +18,7 @@ import { TaxProviderService } from "../../../../services" * medusa.admin.store.listTaxProviders() * .then(({ tax_providers }) => { * console.log(tax_providers.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/store/remove-currency.ts b/packages/medusa/src/api/routes/admin/store/remove-currency.ts index 3040b75f89..79a017351e 100644 --- a/packages/medusa/src/api/routes/admin/store/remove-currency.ts +++ b/packages/medusa/src/api/routes/admin/store/remove-currency.ts @@ -29,7 +29,7 @@ import { EntityManager } from "typeorm" * medusa.admin.store.deleteCurrency("eur") * .then(({ store }) => { * console.log(store.currencies); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/store/update-store.ts b/packages/medusa/src/api/routes/admin/store/update-store.ts index e1875a8a78..28f52bc25c 100644 --- a/packages/medusa/src/api/routes/admin/store/update-store.ts +++ b/packages/medusa/src/api/routes/admin/store/update-store.ts @@ -29,7 +29,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ store }) => { * console.log(store.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -88,7 +88,8 @@ export default async (req, res) => { * description: "The name of the Store" * type: string * swap_link_template: - * description: "A template for Swap links - use `{{cart_id}}` to insert the Swap Cart ID" + * description: >- + * A template for Swap links - use `{{cart_id}}` to insert the Swap Cart ID * type: string * example: "http://example.com/swaps/{{cart_id}}" * payment_link_template: diff --git a/packages/medusa/src/api/routes/admin/swaps/get-swap.ts b/packages/medusa/src/api/routes/admin/swaps/get-swap.ts index 8c2e42c0f1..6d86d0d891 100644 --- a/packages/medusa/src/api/routes/admin/swaps/get-swap.ts +++ b/packages/medusa/src/api/routes/admin/swaps/get-swap.ts @@ -22,7 +22,7 @@ import { SwapService } from "../../../../services" * medusa.admin.swaps.retrieve(swapId) * .then(({ swap }) => { * console.log(swap.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/swaps/index.ts b/packages/medusa/src/api/routes/admin/swaps/index.ts index 0b73125db1..3d18629197 100644 --- a/packages/medusa/src/api/routes/admin/swaps/index.ts +++ b/packages/medusa/src/api/routes/admin/swaps/index.ts @@ -58,6 +58,7 @@ export const defaultAdminSwapFields = [ /** * @schema AdminSwapsListRes * type: object + * description: "The list of swaps with pagination fields." * required: * - swaps * - count @@ -86,6 +87,7 @@ export type AdminSwapsListRes = PaginatedResponse & { /** * @schema AdminSwapsRes * type: object + * description: "The swap's details." * x-expanded-relations: * field: swap * relations: diff --git a/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts b/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts index 27797da4dc..cc4e7198fd 100644 --- a/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts +++ b/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts @@ -28,7 +28,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.swaps.list() * .then(({ swaps }) => { * console.log(swaps.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -80,12 +80,21 @@ export default async (req, res) => { res.json({ swaps, count, offset, limit }) } +/** + * {@inheritDoc FindPaginationParams} + */ export class AdminGetSwapsParams { + /** + * {@inheritDoc FindPaginationParams.limit} + */ @IsInt() @IsOptional() @Type(() => Number) limit?: number = 50 + /** + * {@inheritDoc FindPaginationParams.offset} + */ @IsInt() @IsOptional() @Type(() => Number) diff --git a/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts b/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts index abd7542e6a..410a104663 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts @@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator" * @oas [post] /admin/tax-rates/{id}/product-types/batch * operationId: "PostTaxRatesTaxRateProductTypes" * summary: "Add to Product Types" - * description: "Associates a Tax Rate with a list of Product Types" + * description: "Add Product Types to a Tax Rate." * parameters: * - (path) id=* {string} ID of the tax rate. * - in: query @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -125,6 +125,7 @@ export default async (req, res) => { /** * @schema AdminPostTaxRatesTaxRateProductTypesReq * type: object + * description: "The product types to add to the tax rate." * required: * - product_types * properties: @@ -139,11 +140,20 @@ export class AdminPostTaxRatesTaxRateProductTypesReq { product_types: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminPostTaxRatesTaxRateProductTypesParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts b/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts index 92dd9f74b6..d160aed6fd 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts @@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator" * @oas [post] /admin/tax-rates/{id}/products/batch * operationId: "PostTaxRatesTaxRateProducts" * summary: "Add to Products" - * description: "Associates a Tax Rate with a list of Products." + * description: "Add products to a tax rate." * parameters: * - (path) id=* {string} ID of the tax rate. * - in: query @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -136,11 +136,20 @@ export class AdminPostTaxRatesTaxRateProductsReq { products: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminPostTaxRatesTaxRateProductsParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts b/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts index 6fa4fa3712..aae68ba491 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts @@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator" * @oas [post] /admin/tax-rates/{id}/shipping-options/batch * operationId: "PostTaxRatesTaxRateShippingOptions" * summary: "Add to Shipping Options" - * description: "Associates a Tax Rate with a list of Shipping Options." + * description: "Add Shipping Options to a Tax Rate." * parameters: * - (path) id=* {string} ID of the tax rate. * - in: query @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -138,11 +138,20 @@ export class AdminPostTaxRatesTaxRateShippingOptionsReq { shipping_options: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminPostTaxRatesTaxRateShippingOptionsParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts index 0c464ea4d7..c2a65efcd4 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts @@ -55,7 +55,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -203,11 +203,20 @@ export class AdminPostTaxRatesReq { product_types?: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminPostTaxRatesParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts index 138df5b83b..af311d7eaf 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts @@ -21,7 +21,7 @@ import { TaxRateService } from "../../../../services" * medusa.admin.taxRates.delete(taxRateId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts index e344a7dc9a..967602f826 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts @@ -44,7 +44,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.taxRates.retrieve(taxRateId) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -90,11 +90,20 @@ export default async (req, res) => { res.json({ tax_rate: data }) } +/** + * {@inheritDoc FindParams} + */ export class AdminGetTaxRatesTaxRateParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/index.ts b/packages/medusa/src/api/routes/admin/tax-rates/index.ts index e5362848c8..ea97a40b34 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/index.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/index.ts @@ -121,6 +121,7 @@ export type AdminTaxRatesDeleteRes = DeleteResponse /** * @schema AdminTaxRatesListRes * type: object + * description: "The list of tax rates with pagination fields." * required: * - tax_rates * - count @@ -149,6 +150,7 @@ export type AdminTaxRatesListRes = PaginatedResponse & { /** * @schema AdminTaxRatesRes * type: object + * description: "The tax rate's details." * required: * - tax_rate * properties: diff --git a/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts b/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts index 9184ee33a1..f360432c43 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts @@ -84,7 +84,7 @@ import { validator } from "../../../../utils/validator" * medusa.admin.taxRates.list() * .then(({ tax_rates, limit, offset, count }) => { * console.log(tax_rates.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -141,37 +141,66 @@ export default async (req, res) => { res.json({ tax_rates: data, count, offset: value.offset, limit: value.limit }) } +/** + * Parameters used to filter and configure the pagination of the retrieved tax rates. + */ export class AdminGetTaxRatesParams { + /** + * Filter tax rates by the IDs of their associates region. + */ @IsOptional() @IsType([String, [String]]) region_id?: string | string[] + /** + * Name to filter tax rates by. + */ @IsString() @IsOptional() name?: string + /** + * Code to filter tax rates by. + */ @IsString() @IsOptional() code?: string + /** + * Number filters to filter tax rates' `rate` field. + */ @IsType([NumericalComparisonOperator, Number]) @IsOptional() rate?: number | NumericalComparisonOperator + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset? = 0 + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 50 + */ @IsNumber() @IsOptional() @Type(() => Number) limit? = 50 + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts index 1983c5ac9e..04ac012f12 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -125,6 +125,7 @@ export default async (req, res) => { /** * @schema AdminDeleteTaxRatesTaxRateProductTypesReq * type: object + * description: "Product types to remove from the tax rates." * required: * - product_types * properties: @@ -139,11 +140,20 @@ export class AdminDeleteTaxRatesTaxRateProductTypesReq { product_types: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminDeleteTaxRatesTaxRateProductTypesParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts index fb53d081f1..190fb661f8 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -136,11 +136,20 @@ export class AdminDeleteTaxRatesTaxRateProductsReq { products: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminDeleteTaxRatesTaxRateProductsParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts index edb8986ce4..89ce47e0b4 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -139,11 +139,20 @@ export class AdminDeleteTaxRatesTaxRateShippingOptionsReq { shipping_options: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminDeleteTaxRatesTaxRateShippingOptionsParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts index 42e4fa5894..ee0c1120aa 100644 --- a/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts +++ b/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts @@ -54,7 +54,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ tax_rate }) => { * console.log(tax_rate.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -199,11 +199,20 @@ export class AdminPostTaxRatesTaxRateReq { product_types?: string[] } +/** + * {@inheritDoc FindParams} + */ export class AdminPostTaxRatesTaxRateParams { + /** + * {@inheritDoc FindParams.expand} + */ @IsArray() @IsOptional() expand?: string[] + /** + * {@inheritDoc FindParams.fields} + */ @IsArray() @IsOptional() fields?: string[] diff --git a/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts b/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts index 8b717ab7a4..02a6bbcaa5 100644 --- a/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts +++ b/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts @@ -27,7 +27,7 @@ import { IFileService } from "../../../../interfaces" * medusa.admin.uploads.createProtected(file) * .then(({ uploads }) => { * console.log(uploads.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/uploads/create-upload.ts b/packages/medusa/src/api/routes/admin/uploads/create-upload.ts index b06426a47b..7d40260c88 100644 --- a/packages/medusa/src/api/routes/admin/uploads/create-upload.ts +++ b/packages/medusa/src/api/routes/admin/uploads/create-upload.ts @@ -26,7 +26,7 @@ import fs from "fs" * medusa.admin.uploads.create(file) * .then(({ uploads }) => { * console.log(uploads.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts b/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts index 94c90aa3c5..e016f1e676 100644 --- a/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts +++ b/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts @@ -23,7 +23,7 @@ import { IsString } from "class-validator" * }) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts b/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts index 5fabcd3827..1d518b8f0b 100644 --- a/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts +++ b/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts @@ -24,7 +24,7 @@ import { IsString } from "class-validator" * }) * .then(({ download_url }) => { * console.log(download_url); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/uploads/index.ts b/packages/medusa/src/api/routes/admin/uploads/index.ts index 1908e812ec..d7e27d3984 100644 --- a/packages/medusa/src/api/routes/admin/uploads/index.ts +++ b/packages/medusa/src/api/routes/admin/uploads/index.ts @@ -43,6 +43,7 @@ export default (app) => { /** * @schema AdminUploadsRes * type: object + * description: "The list of uploaded files." * required: * - uploads * properties: @@ -92,6 +93,7 @@ export type AdminDeleteUploadsRes = DeleteResponse /** * @schema AdminUploadsDownloadUrlRes * type: object + * description: "The download URL details." * required: * - download_url * properties: diff --git a/packages/medusa/src/api/routes/admin/users/create-user.ts b/packages/medusa/src/api/routes/admin/users/create-user.ts index dc91175ef4..fd4677308a 100644 --- a/packages/medusa/src/api/routes/admin/users/create-user.ts +++ b/packages/medusa/src/api/routes/admin/users/create-user.ts @@ -32,7 +32,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ user }) => { * console.log(user.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/users/delete-user.ts b/packages/medusa/src/api/routes/admin/users/delete-user.ts index 54e4ea4d9d..fd2e5f2a29 100644 --- a/packages/medusa/src/api/routes/admin/users/delete-user.ts +++ b/packages/medusa/src/api/routes/admin/users/delete-user.ts @@ -21,7 +21,7 @@ import UserService from "../../../../services/user" * medusa.admin.users.delete(userId) * .then(({ id, object, deleted }) => { * console.log(id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/users/get-user.ts b/packages/medusa/src/api/routes/admin/users/get-user.ts index 08a672b206..bbf2c2d77d 100644 --- a/packages/medusa/src/api/routes/admin/users/get-user.ts +++ b/packages/medusa/src/api/routes/admin/users/get-user.ts @@ -20,7 +20,7 @@ import UserService from "../../../../services/user" * medusa.admin.users.retrieve(userId) * .then(({ user }) => { * console.log(user.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/users/index.ts b/packages/medusa/src/api/routes/admin/users/index.ts index 8797e0d27b..867a572ec8 100644 --- a/packages/medusa/src/api/routes/admin/users/index.ts +++ b/packages/medusa/src/api/routes/admin/users/index.ts @@ -38,6 +38,7 @@ export default (app) => { /** * @schema AdminUserRes * type: object + * description: "The user's details." * required: * - user * properties: @@ -52,6 +53,7 @@ export type AdminUserRes = { /** * @schema AdminUsersListRes * type: object + * description: "The list of users." * required: * - users * properties: diff --git a/packages/medusa/src/api/routes/admin/users/list-users.ts b/packages/medusa/src/api/routes/admin/users/list-users.ts index 22b3133c64..1b909e9fd5 100644 --- a/packages/medusa/src/api/routes/admin/users/list-users.ts +++ b/packages/medusa/src/api/routes/admin/users/list-users.ts @@ -18,7 +18,7 @@ import UserService from "../../../../services/user" * medusa.admin.users.list() * .then(({ users }) => { * console.log(users.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/users/reset-password-token.ts b/packages/medusa/src/api/routes/admin/users/reset-password-token.ts index d0c254be0d..77bdd9b182 100644 --- a/packages/medusa/src/api/routes/admin/users/reset-password-token.ts +++ b/packages/medusa/src/api/routes/admin/users/reset-password-token.ts @@ -7,7 +7,9 @@ import { EntityManager } from "typeorm" * @oas [post] /admin/users/password-token * operationId: "PostUsersUserPasswordToken" * summary: "Request Password Reset" - * description: "Generate a password token for an admin user with a given email." + * description: "Generate a password token for an admin user with a given email. This also triggers the `user.password_reset` event. So, if you have a Notification Service installed + * that can handle this event, a notification, such as an email, will be sent to the user. The token is triggered as part of the `user.password_reset` event's payload. + * That token must be used later to reset the password using the [Reset Password](https://docs.medusajs.com/api/admin#users_postusersuserpassword) API Route." * externalDocs: * description: How to reset a user's password * url: https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password @@ -33,7 +35,7 @@ import { EntityManager } from "typeorm" * }) * .catch(() => { * // error occurred - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/users/reset-password.ts b/packages/medusa/src/api/routes/admin/users/reset-password.ts index e83b1e7e83..906944c92e 100644 --- a/packages/medusa/src/api/routes/admin/users/reset-password.ts +++ b/packages/medusa/src/api/routes/admin/users/reset-password.ts @@ -12,7 +12,8 @@ import { EntityManager } from "typeorm" * @oas [post] /admin/users/reset-password * operationId: "PostUsersUserPassword" * summary: "Reset Password" - * description: "Reset the password of an admin User using their reset password token. A user must request to reset their password first before attempting to reset their password with this request." + * description: "Reset the password of an admin User using their reset password token. A user must request to reset their password first before attempting to reset their + * password with this request." * externalDocs: * description: How to reset a user's password * url: https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password @@ -36,7 +37,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ user }) => { * console.log(user.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/users/update-user.ts b/packages/medusa/src/api/routes/admin/users/update-user.ts index 9f5f09c2cf..f2e6762ee0 100644 --- a/packages/medusa/src/api/routes/admin/users/update-user.ts +++ b/packages/medusa/src/api/routes/admin/users/update-user.ts @@ -32,7 +32,7 @@ import { EntityManager } from "typeorm" * }) * .then(({ user }) => { * console.log(user.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/variants/get-inventory.ts b/packages/medusa/src/api/routes/admin/variants/get-inventory.ts index 18a604b6d7..99c2ac453c 100644 --- a/packages/medusa/src/api/routes/admin/variants/get-inventory.ts +++ b/packages/medusa/src/api/routes/admin/variants/get-inventory.ts @@ -192,7 +192,7 @@ export type ResponseInventoryItem = Partial & { * $ref: "#/components/schemas/ResponseInventoryItem" * sales_channel_availability: * type: array - * description: An array of details about the variant's inventory availability in sales channels. + * description: Details about the variant's inventory availability in sales channels. * items: * type: object * required: @@ -223,10 +223,11 @@ export type VariantInventory = { /** * @schema AdminGetVariantsVariantInventoryRes * type: object + * description: "The variant's inventory details." * properties: * variant: * type: object - * description: "The product variant's." + * description: "The product variant's inventory details." * $ref: "#/components/schemas/VariantInventory" */ export type AdminGetVariantsVariantInventoryRes = { diff --git a/packages/medusa/src/api/routes/admin/variants/get-variant.ts b/packages/medusa/src/api/routes/admin/variants/get-variant.ts index 1826d9f23b..6768cae916 100644 --- a/packages/medusa/src/api/routes/admin/variants/get-variant.ts +++ b/packages/medusa/src/api/routes/admin/variants/get-variant.ts @@ -25,7 +25,7 @@ import { FindParams } from "../../../../types/common" * medusa.admin.variants.retrieve(variantId) * .then(({ variant }) => { * console.log(variant.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/admin/variants/index.ts b/packages/medusa/src/api/routes/admin/variants/index.ts index ab917ea2f2..b9cf659863 100644 --- a/packages/medusa/src/api/routes/admin/variants/index.ts +++ b/packages/medusa/src/api/routes/admin/variants/index.ts @@ -75,6 +75,7 @@ export const defaultAdminVariantFields: (keyof ProductVariant)[] = [ /** * @schema AdminVariantsListRes * type: object + * description: "The list of variants with pagination fields." * x-expanded-relations: * field: variants * relations: @@ -111,6 +112,7 @@ export type AdminVariantsListRes = PaginatedResponse & { /** * @schema AdminVariantsRes * type: object + * description: "The product variant's details." * x-expanded-relations: * field: variant * relations: diff --git a/packages/medusa/src/api/routes/admin/variants/list-variants.ts b/packages/medusa/src/api/routes/admin/variants/list-variants.ts index 73a7c035b0..901e4c41f0 100644 --- a/packages/medusa/src/api/routes/admin/variants/list-variants.ts +++ b/packages/medusa/src/api/routes/admin/variants/list-variants.ts @@ -125,7 +125,7 @@ import { omit } from "lodash" * medusa.admin.variants.list() * .then(({ variants, limit, offset, count }) => { * console.log(variants.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -230,37 +230,66 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product variants. + */ export class AdminGetVariantsParams extends AdminPriceSelectionParams { + /** + * Search term to search product variants' IDs. + */ @IsOptional() @IsString() q?: string + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 20 + */ @IsOptional() @IsInt() @Type(() => Number) limit?: number = 20 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsInt() @Type(() => Number) offset?: number = 0 + /** + * {@inheritDoc FindParams.expand} + */ @IsOptional() @IsString() expand?: string + /** + * {@inheritDoc FindParams.fields} + */ @IsString() @IsOptional() fields?: string + /** + * IDs to filter product variants by. + */ @IsOptional() @IsType([String, [String]]) id?: string | string[] + /** + * Titles to filter product variants by. + */ @IsOptional() @IsType([String, [String]]) title?: string | string[] + /** + * Number filters to apply on product variants' `inventory_quantity` field. + */ @IsOptional() @IsType([Number, NumericalComparisonOperator]) inventory_quantity?: number | NumericalComparisonOperator diff --git a/packages/medusa/src/api/routes/store/auth/create-session.ts b/packages/medusa/src/api/routes/store/auth/create-session.ts index 4df5e13ff6..d895080542 100644 --- a/packages/medusa/src/api/routes/store/auth/create-session.ts +++ b/packages/medusa/src/api/routes/store/auth/create-session.ts @@ -31,7 +31,7 @@ import { defaultRelations } from "." * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/auth/delete-session.ts b/packages/medusa/src/api/routes/store/auth/delete-session.ts index 296ca5e036..02c25887a3 100644 --- a/packages/medusa/src/api/routes/store/auth/delete-session.ts +++ b/packages/medusa/src/api/routes/store/auth/delete-session.ts @@ -7,6 +7,15 @@ * x-codegen: * method: deleteSession * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * medusa.auth.deleteSession() + * .then(() => { + * // customer logged out successfully + * }) * - lang: Shell * label: cURL * source: | @@ -34,9 +43,11 @@ * $ref: "#/components/responses/500_error" */ export default async (req, res) => { - if(req.session.user_id) { // if we are also logged in as a user, persist that session + if (req.session.user_id) { + // if we are also logged in as a user, persist that session delete req.session.customer_id - } else { // otherwise, destroy the session + } else { + // otherwise, destroy the session req.session.destroy() } diff --git a/packages/medusa/src/api/routes/store/auth/get-session.ts b/packages/medusa/src/api/routes/store/auth/get-session.ts index 028e5b13e7..654ba31aa6 100644 --- a/packages/medusa/src/api/routes/store/auth/get-session.ts +++ b/packages/medusa/src/api/routes/store/auth/get-session.ts @@ -19,7 +19,7 @@ import { defaultRelations } from "." * medusa.auth.getSession() * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/auth/get-token.ts b/packages/medusa/src/api/routes/store/auth/get-token.ts index 7e0287ca11..6930ffff5c 100644 --- a/packages/medusa/src/api/routes/store/auth/get-token.ts +++ b/packages/medusa/src/api/routes/store/auth/get-token.ts @@ -30,7 +30,7 @@ import { StorePostAuthReq } from "./create-session" * }) * .then(({ access_token }) => { * console.log(access_token); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/auth/index.ts b/packages/medusa/src/api/routes/store/auth/index.ts index de25b355c6..6f329c824c 100644 --- a/packages/medusa/src/api/routes/store/auth/index.ts +++ b/packages/medusa/src/api/routes/store/auth/index.ts @@ -25,6 +25,7 @@ export const defaultRelations = ["orders", "orders.items", "shipping_addresses"] /** * @schema StoreAuthRes * type: object + * description: "The customer's details." * x-expanded-relations: * field: customer * relations: @@ -45,6 +46,7 @@ export type StoreAuthRes = { /** * @schema StoreBearerAuthRes * type: object + * description: "The access token details." * properties: * access_token: * description: Access token that can be used to send authenticated requests. @@ -57,6 +59,7 @@ export type StoreBearerAuthRes = { /** * @schema StoreGetAuthEmailRes * type: object + * description: "Details on whether the email exists." * required: * - exists * properties: diff --git a/packages/medusa/src/api/routes/store/carts/add-shipping-method.ts b/packages/medusa/src/api/routes/store/carts/add-shipping-method.ts index 7caa5c30c4..9c3f9130e0 100644 --- a/packages/medusa/src/api/routes/store/carts/add-shipping-method.ts +++ b/packages/medusa/src/api/routes/store/carts/add-shipping-method.ts @@ -33,7 +33,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/complete-cart.ts b/packages/medusa/src/api/routes/store/carts/complete-cart.ts index 5ad68269e2..bfc204d516 100644 --- a/packages/medusa/src/api/routes/store/carts/complete-cart.ts +++ b/packages/medusa/src/api/routes/store/carts/complete-cart.ts @@ -9,7 +9,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * summary: "Complete a Cart" * operationId: "PostCartsCartComplete" * description: | - * Complete a cart and place an order or create a swap, based on what the cart is created for. This includes attempting to authorize the cart's payment. + * Complete a cart and place an order or create a swap, based on the cart's type. This includes attempting to authorize the cart's payment. * If authorizing the payment requires more action, the cart will not be completed and the order will not be placed or the swap will not be created. * * An idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to @@ -31,7 +31,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.complete(cartId) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/create-cart.ts b/packages/medusa/src/api/routes/store/carts/create-cart.ts index f562767a6b..ad34bf0ffb 100644 --- a/packages/medusa/src/api/routes/store/carts/create-cart.ts +++ b/packages/medusa/src/api/routes/store/carts/create-cart.ts @@ -38,7 +38,7 @@ import reqIp from "request-ip" * Create a Cart. Although optional, specifying the cart's region and sales channel can affect the cart's pricing and * the products that can be added to the cart respectively. So, make sure to set those early on and change them if necessary, such as when the customer changes their region. * - * If a customer is logged in, the cart's customer ID and email will automatically be set. + * If a customer is logged in, make sure to pass its ID or email within the cart's details so that the cart is attached to the customer. * requestBody: * content: * application/json: @@ -55,7 +55,7 @@ import reqIp from "request-ip" * medusa.carts.create() * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -244,6 +244,7 @@ export class Item { /** * @schema StorePostCartReq * type: object + * description: "The details of the cart to be created." * properties: * region_id: * type: string @@ -259,7 +260,7 @@ export class Item { * the cart will not be associated with any sales channel." * country_code: * type: string - * description: "The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address." + * description: "The two character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address." * externalDocs: * url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements * description: See a list of codes. @@ -279,7 +280,8 @@ export class Item { * description: The quantity to add into the cart. * type: integer * context: - * description: "An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`" + * description: >- + * An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent` * type: object * example: * ip: "::1" diff --git a/packages/medusa/src/api/routes/store/carts/create-line-item/index.ts b/packages/medusa/src/api/routes/store/carts/create-line-item/index.ts index 36523cce14..36fee1e21b 100644 --- a/packages/medusa/src/api/routes/store/carts/create-line-item/index.ts +++ b/packages/medusa/src/api/routes/store/carts/create-line-item/index.ts @@ -40,7 +40,7 @@ import { cleanResponseData } from "../../../../../utils/clean-response-data" * }) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/create-payment-sessions.ts b/packages/medusa/src/api/routes/store/carts/create-payment-sessions.ts index 67bf8cd56a..a7ee8f308d 100644 --- a/packages/medusa/src/api/routes/store/carts/create-payment-sessions.ts +++ b/packages/medusa/src/api/routes/store/carts/create-payment-sessions.ts @@ -12,7 +12,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [post] /store/carts/{id}/payment-sessions * operationId: "PostCartsCartPaymentSessions" * summary: "Create Payment Sessions" - * description: "Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there only one payment session is created, + * description: "Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there's only one payment session created, * it will be selected by default. The creation of the payment session uses the payment provider and may require sending requests to third-party services." * parameters: * - (path) id=* {string} The ID of the Cart. @@ -27,7 +27,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.createPaymentSessions(cartId) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/delete-discount.ts b/packages/medusa/src/api/routes/store/carts/delete-discount.ts index f940eb3b55..2439576ddd 100644 --- a/packages/medusa/src/api/routes/store/carts/delete-discount.ts +++ b/packages/medusa/src/api/routes/store/carts/delete-discount.ts @@ -11,7 +11,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * @oas [delete] /store/carts/{id}/discounts/{code} * operationId: DeleteCartsCartDiscountsDiscount * summary: "Remove Discount" - * description: "Remove a Discount from a Cart. This only removes the application of the discount, and not completely delete it. The totals will be re-calculated and the payment sessions + * description: "Remove a Discount from a Cart. This only removes the application of the discount, and not completely deletes it. The totals will be re-calculated and the payment sessions * will be refreshed after the removal." * parameters: * - (path) id=* {string} The ID of the Cart. @@ -27,7 +27,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.deleteDiscount(cartId, code) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/delete-line-item.ts b/packages/medusa/src/api/routes/store/carts/delete-line-item.ts index 0d31b1295a..7f63f0d93b 100644 --- a/packages/medusa/src/api/routes/store/carts/delete-line-item.ts +++ b/packages/medusa/src/api/routes/store/carts/delete-line-item.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.lineItems.delete(cartId, lineId) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/delete-payment-session.ts b/packages/medusa/src/api/routes/store/carts/delete-payment-session.ts index 0cca8e5783..096e7f9bcb 100644 --- a/packages/medusa/src/api/routes/store/carts/delete-payment-session.ts +++ b/packages/medusa/src/api/routes/store/carts/delete-payment-session.ts @@ -26,7 +26,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.deletePaymentSession(cartId, "manual") * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/get-cart.ts b/packages/medusa/src/api/routes/store/carts/get-cart.ts index 053315df43..5da2e384b7 100644 --- a/packages/medusa/src/api/routes/store/carts/get-cart.ts +++ b/packages/medusa/src/api/routes/store/carts/get-cart.ts @@ -25,7 +25,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.retrieve(cartId) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/index.ts b/packages/medusa/src/api/routes/store/carts/index.ts index af0694dc69..e4fa98227b 100644 --- a/packages/medusa/src/api/routes/store/carts/index.ts +++ b/packages/medusa/src/api/routes/store/carts/index.ts @@ -237,6 +237,7 @@ export const defaultStoreCartRelations = [ /** * @schema StoreCartsRes * type: object + * description: "The cart's details." * x-expanded-relations: * field: cart * relations: @@ -307,15 +308,17 @@ export type StoreCartsRes = { /** * @schema StoreCompleteCartRes * type: object + * description: "If the cart is completed successfully, this will have the created order or the swap's details, based on the cart's type. Otherwise, it'll be the cart's details." * required: * - type * - data * properties: * type: * type: string - * description: "The type of the data property. If the cart completion fails, type will be `cart` and the data object will be the cart's details. - * If the cart completion is successful and the cart is used for checkout, type will be `order` and the data object will be the order's details. - * If the cart completion is successful and the cart is used for swap creation, type will be `swap` and the data object will be the swap's details." + * description: >- + * The type of the data property. If the cart completion fails, type will be `cart` and the data object will be the cart's details. + * If the cart completion is successful and the cart is used for checkout, type will be `order` and the data object will be the order's details. + * If the cart completion is successful and the cart is used for swap creation, type will be `swap` and the data object will be the swap's details. * enum: [order, cart, swap] * data: * type: object diff --git a/packages/medusa/src/api/routes/store/carts/refresh-payment-session.ts b/packages/medusa/src/api/routes/store/carts/refresh-payment-session.ts index c5109ab5ef..667def0f01 100644 --- a/packages/medusa/src/api/routes/store/carts/refresh-payment-session.ts +++ b/packages/medusa/src/api/routes/store/carts/refresh-payment-session.ts @@ -21,7 +21,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.carts.refreshPaymentSession(cartId, "manual") * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/set-payment-session.ts b/packages/medusa/src/api/routes/store/carts/set-payment-session.ts index a830ff22b9..98d54a9f14 100644 --- a/packages/medusa/src/api/routes/store/carts/set-payment-session.ts +++ b/packages/medusa/src/api/routes/store/carts/set-payment-session.ts @@ -34,7 +34,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/update-cart.ts b/packages/medusa/src/api/routes/store/carts/update-cart.ts index 6f08ccd76f..ad55c172cf 100644 --- a/packages/medusa/src/api/routes/store/carts/update-cart.ts +++ b/packages/medusa/src/api/routes/store/carts/update-cart.ts @@ -45,7 +45,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -247,7 +247,8 @@ class Discount { * description: "The ID of the Customer to associate the Cart with." * type: string * context: - * description: "An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`" + * description: >- + * An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent` * type: object * example: * ip: "::1" diff --git a/packages/medusa/src/api/routes/store/carts/update-line-item.ts b/packages/medusa/src/api/routes/store/carts/update-line-item.ts index a107760f26..f927968e95 100644 --- a/packages/medusa/src/api/routes/store/carts/update-line-item.ts +++ b/packages/medusa/src/api/routes/store/carts/update-line-item.ts @@ -36,7 +36,7 @@ import { handleAddOrUpdateLineItem } from "./create-line-item/utils/handler-step * }) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/carts/update-payment-session.ts b/packages/medusa/src/api/routes/store/carts/update-payment-session.ts index ecfd9757cc..07c569e307 100644 --- a/packages/medusa/src/api/routes/store/carts/update-payment-session.ts +++ b/packages/medusa/src/api/routes/store/carts/update-payment-session.ts @@ -37,7 +37,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * }) * .then(({ cart }) => { * console.log(cart.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/collections/get-collection.ts b/packages/medusa/src/api/routes/store/collections/get-collection.ts index fce80e8dba..5ea9712a9c 100644 --- a/packages/medusa/src/api/routes/store/collections/get-collection.ts +++ b/packages/medusa/src/api/routes/store/collections/get-collection.ts @@ -18,7 +18,7 @@ import ProductCollectionService from "../../../../services/product-collection" * medusa.collections.retrieve(collectionId) * .then(({ collection }) => { * console.log(collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/collections/index.ts b/packages/medusa/src/api/routes/store/collections/index.ts index 90ff75d121..90376494f6 100644 --- a/packages/medusa/src/api/routes/store/collections/index.ts +++ b/packages/medusa/src/api/routes/store/collections/index.ts @@ -38,6 +38,7 @@ export const allowedFields = [ /** * @schema StoreCollectionsListRes * type: object + * description: "The list of product collections with pagination fields." * required: * - collections * - count @@ -66,6 +67,7 @@ export type StoreCollectionsListRes = PaginatedResponse & { /** * @schema StoreCollectionsRes * type: object + * description: "The details of the product collection." * required: * - collection * properties: diff --git a/packages/medusa/src/api/routes/store/collections/list-collections.ts b/packages/medusa/src/api/routes/store/collections/list-collections.ts index 6c502b0b9d..1262175aa7 100644 --- a/packages/medusa/src/api/routes/store/collections/list-collections.ts +++ b/packages/medusa/src/api/routes/store/collections/list-collections.ts @@ -77,7 +77,7 @@ import { Type } from "class-transformer" * medusa.collections.list() * .then(({ collections, limit, offset, count }) => { * console.log(collections.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -118,26 +118,46 @@ export default async (req, res) => { res.status(200).json({ collections, count, limit: take, offset: skip }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product collections. + */ export class StoreGetCollectionsParams { + /** + * Handles to filter product collections by. + */ @IsOptional() @IsArray() handle?: string[] + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 10 + */ @IsOptional() @IsInt() @Type(() => Number) limit?: number = 10 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsInt() @Type(() => Number) offset?: number = 0 + /** + * Date filters to apply on the product collections' `created_at` date + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the product collections' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/api/routes/store/customers/create-address.ts b/packages/medusa/src/api/routes/store/customers/create-address.ts index 876afcfe20..e34121b657 100644 --- a/packages/medusa/src/api/routes/store/customers/create-address.ts +++ b/packages/medusa/src/api/routes/store/customers/create-address.ts @@ -41,7 +41,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/create-customer.ts b/packages/medusa/src/api/routes/store/customers/create-customer.ts index 52d69a5ce9..15b896aa2d 100644 --- a/packages/medusa/src/api/routes/store/customers/create-customer.ts +++ b/packages/medusa/src/api/routes/store/customers/create-customer.ts @@ -35,7 +35,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/delete-address.ts b/packages/medusa/src/api/routes/store/customers/delete-address.ts index a8e742344d..2cfd4dc8fb 100644 --- a/packages/medusa/src/api/routes/store/customers/delete-address.ts +++ b/packages/medusa/src/api/routes/store/customers/delete-address.ts @@ -23,7 +23,7 @@ import CustomerService from "../../../../services/customer" * medusa.customers.addresses.deleteAddress(addressId) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/get-customer.ts b/packages/medusa/src/api/routes/store/customers/get-customer.ts index f10f6ca019..51cc9dbe01 100644 --- a/packages/medusa/src/api/routes/store/customers/get-customer.ts +++ b/packages/medusa/src/api/routes/store/customers/get-customer.ts @@ -19,7 +19,7 @@ import CustomerService from "../../../../services/customer" * medusa.customers.retrieve() * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/get-payment-methods.ts b/packages/medusa/src/api/routes/store/customers/get-payment-methods.ts index 108e90840f..b4c9380f64 100644 --- a/packages/medusa/src/api/routes/store/customers/get-payment-methods.ts +++ b/packages/medusa/src/api/routes/store/customers/get-payment-methods.ts @@ -24,7 +24,7 @@ import { promiseAll } from "@medusajs/utils" * medusa.customers.paymentMethods.list() * .then(({ payment_methods }) => { * console.log(payment_methods.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/index.ts b/packages/medusa/src/api/routes/store/customers/index.ts index 014313f97c..7a9459ae60 100644 --- a/packages/medusa/src/api/routes/store/customers/index.ts +++ b/packages/medusa/src/api/routes/store/customers/index.ts @@ -114,6 +114,7 @@ export const allowedStoreCustomersFields = [ /** * @schema StoreCustomersRes * type: object + * description: "The customer's details." * x-expanded-relations: * field: customer * relations: @@ -147,6 +148,7 @@ export type StoreCustomersResetPasswordRes = { /** * @schema StoreCustomersListOrdersRes * type: object + * description: "The list of the customer's orders with pagination fields." * x-expanded-relations: * field: orders * relations: @@ -257,12 +259,13 @@ export type StoreCustomersListOrdersRes = PaginatedResponse & { /** * @schema StoreCustomersListPaymentMethodsRes * type: object + * description: "The payment method's details." * required: * - payment_methods * properties: * payment_methods: * type: array - * description: "An array of saved payment method details." + * description: "The details of the saved payment methods." * items: * type: object * required: diff --git a/packages/medusa/src/api/routes/store/customers/list-orders.ts b/packages/medusa/src/api/routes/store/customers/list-orders.ts index 597a26fc5a..a52fe76567 100644 --- a/packages/medusa/src/api/routes/store/customers/list-orders.ts +++ b/packages/medusa/src/api/routes/store/customers/list-orders.ts @@ -153,7 +153,7 @@ import { DateComparisonOperator } from "../../../../types/common" * medusa.customers.listOrders() * .then(({ orders, limit, offset, count }) => { * console.log(orders); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -204,82 +204,144 @@ export default async (req: Request, res: Response) => { res.json({ orders, count, offset: offset, limit: limit }) } +/** + * {@inheritDoc FindPaginationParams} + */ export class StoreGetCustomersCustomerOrdersPaginationParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 10 + */ @IsOptional() @IsNumber() @Type(() => Number) limit = 10 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsNumber() @Type(() => Number) offset = 0 + /** + * {@inheritDoc FindParams.fields} + */ @IsOptional() @IsString() fields?: string + /** + * {@inheritDoc FindParams.expand} + */ @IsOptional() @IsString() expand?: string } +/** + * Parameters used to filter and configure the pagination of the retrieved orders. + */ // eslint-disable-next-line max-len export class StoreGetCustomersCustomerOrdersParams extends StoreGetCustomersCustomerOrdersPaginationParams { + /** + * ID to filter orders by. + */ @IsString() @IsOptional() id?: string + /** + * Search term to search orders' display ID, email, shipping address's first name, customer's first name, customer's last name, and customer's phone number. + */ @IsString() @IsOptional() q?: string + /** + * Statuses to filter orders by. + */ @IsOptional() @IsEnum(OrderStatus, { each: true }) status?: OrderStatus[] + /** + * Fulfillment statuses to filter orders by. + */ @IsOptional() @IsEnum(FulfillmentStatus, { each: true }) fulfillment_status?: FulfillmentStatus[] + /** + * Payment statuses to filter orders by. + */ @IsOptional() @IsEnum(PaymentStatus, { each: true }) payment_status?: PaymentStatus[] + /** + * Display ID to filter orders by. + */ @IsString() @IsOptional() display_id?: string + /** + * Cart ID to filter orders by. + */ @IsString() @IsOptional() cart_id?: string + /** + * Email to filter orders by. + */ @IsString() @IsOptional() email?: string + /** + * Region ID to filter orders by. + */ @IsString() @IsOptional() region_id?: string + /** + * Currency code to filter orders by. + */ @IsString() @IsOptional() currency_code?: string + /** + * Tax rate to filter orders by. + */ @IsString() @IsOptional() tax_rate?: string + /** + * Date filters to apply on the orders' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the orders' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the orders' `canceled_at` date. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/api/routes/store/customers/reset-password.ts b/packages/medusa/src/api/routes/store/customers/reset-password.ts index a569078331..abc18b40f9 100644 --- a/packages/medusa/src/api/routes/store/customers/reset-password.ts +++ b/packages/medusa/src/api/routes/store/customers/reset-password.ts @@ -35,7 +35,7 @@ import { MedusaError } from "medusa-core-utils" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/update-address.ts b/packages/medusa/src/api/routes/store/customers/update-address.ts index c0bdd033f6..5f1e3abb74 100644 --- a/packages/medusa/src/api/routes/store/customers/update-address.ts +++ b/packages/medusa/src/api/routes/store/customers/update-address.ts @@ -32,7 +32,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/customers/update-customer.ts b/packages/medusa/src/api/routes/store/customers/update-customer.ts index fc9df54a11..309256b868 100644 --- a/packages/medusa/src/api/routes/store/customers/update-customer.ts +++ b/packages/medusa/src/api/routes/store/customers/update-customer.ts @@ -32,7 +32,7 @@ import { IsType } from "../../../../utils/validators/is-type" * }) * .then(({ customer }) => { * console.log(customer.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/gift-cards/get-gift-card.ts b/packages/medusa/src/api/routes/store/gift-cards/get-gift-card.ts index 35833f2cf0..20bdd66a13 100644 --- a/packages/medusa/src/api/routes/store/gift-cards/get-gift-card.ts +++ b/packages/medusa/src/api/routes/store/gift-cards/get-gift-card.ts @@ -20,7 +20,7 @@ import GiftCardService from "../../../../services/gift-card" * medusa.giftCards.retrieve(code) * .then(({ gift_card }) => { * console.log(gift_card.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/gift-cards/index.ts b/packages/medusa/src/api/routes/store/gift-cards/index.ts index b4e0d2ea57..b1d06290b9 100644 --- a/packages/medusa/src/api/routes/store/gift-cards/index.ts +++ b/packages/medusa/src/api/routes/store/gift-cards/index.ts @@ -27,6 +27,7 @@ export const allowedStoreGiftCardFields = ["id", "code", "value", "balance"] /** * @schema StoreGiftCardsRes + * description: "The gift card's details." * type: object * required: * - gift_card diff --git a/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts b/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts index 07153499a0..59763d572b 100644 --- a/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts +++ b/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts @@ -27,9 +27,9 @@ import { * import Medusa from "@medusajs/medusa-js" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * medusa.orderEdits.complete(orderEditId) - * .then(({ order_edit }) => { - * console.log(order_edit.id) - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts b/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts index 4ef556e55d..44e1457be4 100644 --- a/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts +++ b/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts @@ -28,9 +28,9 @@ import { * import Medusa from "@medusajs/medusa-js" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * medusa.orderEdits.decline(orderEditId) - * .then(({ order_edit }) => { - * console.log(order_edit.id); - * }) + * .then(({ order_edit }) => { + * console.log(order_edit.id); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts b/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts index 8fcad8fd0b..bdf322b074 100644 --- a/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts +++ b/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts @@ -19,7 +19,7 @@ import { OrderEditService } from "../../../../services" * medusa.orderEdits.retrieve(orderEditId) * .then(({ order_edit }) => { * console.log(order_edit.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/order-edits/index.ts b/packages/medusa/src/api/routes/store/order-edits/index.ts index baf5792ac8..531aee1125 100644 --- a/packages/medusa/src/api/routes/store/order-edits/index.ts +++ b/packages/medusa/src/api/routes/store/order-edits/index.ts @@ -44,6 +44,7 @@ export default (app) => { /** * @schema StoreOrderEditsRes * type: object + * description: "The order edit's details." * x-expanded-relations: * field: order_edit * relations: diff --git a/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts b/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts index 7a2c09d596..da60340836 100644 --- a/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts +++ b/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts @@ -37,7 +37,7 @@ import { promiseAll } from "@medusajs/utils" * }) * .catch(() => { * // an error occurred - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/orders/get-order-by-cart.ts b/packages/medusa/src/api/routes/store/orders/get-order-by-cart.ts index 601ee0e08d..b51eaab656 100644 --- a/packages/medusa/src/api/routes/store/orders/get-order-by-cart.ts +++ b/packages/medusa/src/api/routes/store/orders/get-order-by-cart.ts @@ -19,7 +19,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.orders.retrieveByCartId(cartId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/orders/get-order.ts b/packages/medusa/src/api/routes/store/orders/get-order.ts index 3df2fec985..5518957f7f 100644 --- a/packages/medusa/src/api/routes/store/orders/get-order.ts +++ b/packages/medusa/src/api/routes/store/orders/get-order.ts @@ -22,7 +22,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data" * medusa.orders.retrieve(orderId) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/orders/index.ts b/packages/medusa/src/api/routes/store/orders/index.ts index 357b84f5e9..f2be3de834 100644 --- a/packages/medusa/src/api/routes/store/orders/index.ts +++ b/packages/medusa/src/api/routes/store/orders/index.ts @@ -130,6 +130,7 @@ export const allowedStoreOrdersFields = [ /** * @schema StoreOrdersRes * type: object + * description: "The order's details." * required: * - order * x-expanded-relations: diff --git a/packages/medusa/src/api/routes/store/orders/lookup-order.ts b/packages/medusa/src/api/routes/store/orders/lookup-order.ts index 0f0c438a1d..d6062de497 100644 --- a/packages/medusa/src/api/routes/store/orders/lookup-order.ts +++ b/packages/medusa/src/api/routes/store/orders/lookup-order.ts @@ -55,7 +55,7 @@ import { FindParams } from "../../../../types/common" * }) * .then(({ order }) => { * console.log(order.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -105,20 +105,38 @@ export default async (req, res) => { }) } +/** + * Filters to apply on the order's shipping address. + */ export class ShippingAddressPayload { + /** + * Postal code. + */ @IsOptional() @IsString() postal_code?: string } +/** + * Filters to narrow down the looked-up order, with configurations applied on the retrieved order. + */ export class StoreGetOrdersParams extends FindParams { + /** + * Display ID of the order. + */ @IsNumber() @Type(() => Number) display_id: number + /** + * Email of the order. + */ @IsEmail() email: string + /** + * Filter the retrieved order by its shipping address details. + */ @IsOptional() @ValidateNested() @Type(() => ShippingAddressPayload) diff --git a/packages/medusa/src/api/routes/store/orders/request-order.ts b/packages/medusa/src/api/routes/store/orders/request-order.ts index af41e0954a..c5fd6fd780 100644 --- a/packages/medusa/src/api/routes/store/orders/request-order.ts +++ b/packages/medusa/src/api/routes/store/orders/request-order.ts @@ -39,7 +39,7 @@ import { TokenEvents } from "../../../../types/token" * }) * .catch(() => { * // an error occurred - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts b/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts index 0a85a675e3..22d885a8e9 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts @@ -26,7 +26,7 @@ import { PaymentCollectionService } from "../../../../services" * medusa.paymentCollections.authorize(paymentId) * .then(({ payment_collection }) => { * console.log(payment_collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts index cf6ef8c040..e4fb4d6fcf 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts @@ -9,7 +9,7 @@ import { PaymentCollectionService } from "../../../../services" * description: "Authorize a Payment Session of a Payment Collection." * x-authenticated: false * parameters: - * - (path) id=* {string} The ID of the Payment Collections. + * - (path) id=* {string} The ID of the Payment Collection. * - (path) session_id=* {string} The ID of the Payment Session. * x-codegen: * method: authorizePaymentSession @@ -23,7 +23,7 @@ import { PaymentCollectionService } from "../../../../services" * medusa.paymentCollections.authorize(paymentId, sessionId) * .then(({ payment_collection }) => { * console.log(payment_collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts index 504e67b6ef..3e25611097 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts @@ -22,9 +22,9 @@ import { FindParams } from "../../../../types/common" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.paymentCollections.retrieve(paymentCollectionId) - * .then(({ payment_collection }) => { - * console.log(payment_collection.id) - * }) + * .then(({ payment_collection }) => { + * console.log(payment_collection.id) + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/payment-collections/index.ts b/packages/medusa/src/api/routes/store/payment-collections/index.ts index 61f808bafe..3d0349e3f0 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/index.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/index.ts @@ -74,6 +74,7 @@ export const defaultPaymentCollectionRelations = ["region", "payment_sessions"] /** * @schema StorePaymentCollectionsRes * type: object + * description: "The payment collection's details." * x-expanded-relations: * field: payment_collection * relations: diff --git a/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts b/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts index cdf3b34dba..646bb0a362 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts @@ -11,7 +11,7 @@ import { PaymentCollectionService } from "../../../../services" * description: "Create, update, or delete a list of payment sessions of a Payment Collections. If a payment session is not provided in the `sessions` array, it's deleted." * x-authenticated: false * parameters: - * - (path) id=* {string} The ID of the Payment Collections. + * - (path) id=* {string} The ID of the Payment Collection. * requestBody: * content: * application/json: @@ -44,7 +44,7 @@ import { PaymentCollectionService } from "../../../../services" * }) * .then(({ payment_collection }) => { * console.log(payment_collection.id); - * }); + * }) * * // Example 2: Updating one session and removing the other * medusa.paymentCollections.managePaymentSessionsBatch(paymentId, { @@ -58,7 +58,7 @@ import { PaymentCollectionService } from "../../../../services" * }) * .then(({ payment_collection }) => { * console.log(payment_collection.id); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -143,7 +143,7 @@ export class StorePostPaymentCollectionsSessionsReq { * - sessions * properties: * sessions: - * description: "An array of payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted." + * description: "Payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted." * type: array * items: * type: object diff --git a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts index 8af599c528..bb01a1ef3f 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts @@ -28,8 +28,7 @@ import { PaymentCollectionService } from "../../../../services" * medusa.paymentCollections.managePaymentSession(payment_id, { provider_id: "stripe" }) * .then(({ payment_collection }) => { * console.log(payment_collection.id); - * }); - * + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts index 5edc0fc7f2..5800b4fe2d 100644 --- a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts +++ b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts @@ -21,7 +21,7 @@ import { PaymentCollectionService } from "../../../../services" * medusa.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId) * .then(({ payment_session }) => { * console.log(payment_session.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts b/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts index 73e1511592..ea29d8381a 100644 --- a/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts +++ b/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts @@ -26,9 +26,9 @@ import { defaultStoreCategoryScope } from "." * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * // must be previously logged in or use api token * medusa.productCategories.retrieve(productCategoryId) - * .then(({ product_category }) => { - * console.log(product_category.id); - * }); + * .then(({ product_category }) => { + * console.log(product_category.id); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/product-categories/index.ts b/packages/medusa/src/api/routes/store/product-categories/index.ts index 7629f3ec1b..200d367623 100644 --- a/packages/medusa/src/api/routes/store/product-categories/index.ts +++ b/packages/medusa/src/api/routes/store/product-categories/index.ts @@ -76,6 +76,7 @@ export const allowedStoreProductCategoryFields = [ /** * @schema StoreGetProductCategoriesCategoryRes * type: object + * description: "The product category's details." * x-expanded-relations: * field: product_category * relations: @@ -95,6 +96,7 @@ export type StoreGetProductCategoriesCategoryRes = { /** * @schema StoreGetProductCategoriesRes * type: object + * description: "The list of product categories with pagination fields." * x-expanded-relations: * field: product_categories * relations: diff --git a/packages/medusa/src/api/routes/store/product-categories/list-product-categories.ts b/packages/medusa/src/api/routes/store/product-categories/list-product-categories.ts index 30540e99e2..41892d7aa8 100644 --- a/packages/medusa/src/api/routes/store/product-categories/list-product-categories.ts +++ b/packages/medusa/src/api/routes/store/product-categories/list-product-categories.ts @@ -38,7 +38,7 @@ import { defaultStoreCategoryScope } from "." * medusa.productCategories.list() * .then(({ product_categories, limit, offset, count }) => { * console.log(product_categories.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -96,18 +96,32 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product categories. + * + * @property {number} limit - Limit the number of product categories returned in the list. Default is `100`. + */ export class StoreGetProductCategoriesParams extends extendedFindParamsMixin({ limit: 100, offset: 0, }) { + /** + * Search term to search product categories' names and handles. + */ @IsString() @IsOptional() q?: string + /** + * Handle to filter product categories by. + */ @IsString() @IsOptional() handle?: string + /** + * Filter product categories by the ID of their associated parent category. + */ @IsString() @IsOptional() @Transform(({ value }) => { @@ -115,6 +129,9 @@ export class StoreGetProductCategoriesParams extends extendedFindParamsMixin({ }) parent_category_id?: string | null + /** + * Whether to include child categories in the retrieved categories. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value)) diff --git a/packages/medusa/src/api/routes/store/product-tags/index.ts b/packages/medusa/src/api/routes/store/product-tags/index.ts index 3524fd3133..384a771293 100644 --- a/packages/medusa/src/api/routes/store/product-tags/index.ts +++ b/packages/medusa/src/api/routes/store/product-tags/index.ts @@ -37,6 +37,7 @@ export const defaultStoreProductTagRelations = [] /** * @schema StoreProductTagsListRes * type: object + * description: "The list of product tags with pagination fields." * required: * - product_tags * - count diff --git a/packages/medusa/src/api/routes/store/product-tags/list-product-tags.ts b/packages/medusa/src/api/routes/store/product-tags/list-product-tags.ts index 69e3765f58..7ffd40e4c8 100644 --- a/packages/medusa/src/api/routes/store/product-tags/list-product-tags.ts +++ b/packages/medusa/src/api/routes/store/product-tags/list-product-tags.ts @@ -95,7 +95,7 @@ import { IsType } from "../../../../utils/validators/is-type" * medusa.productTags.list() * .then(({ product_tags }) => { * console.log(product_tags.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -141,31 +141,55 @@ export default async (req: Request, res: Response) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product tags. + */ export class StoreGetProductTagsParams extends FindPaginationParams { + /** + * IDs to filter product tags by. + */ @IsType([String, [String], StringComparisonOperator]) @IsOptional() id?: string | string[] | StringComparisonOperator + /** + * Search term to search product tags' values. + */ @IsString() @IsOptional() q?: string + /** + * Values to filter product tags by. + */ @IsType([String, [String], StringComparisonOperator]) @IsOptional() value?: string | string[] | StringComparisonOperator + /** + * Date filters to apply to the product tags' `created_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() created_at?: DateComparisonOperator + /** + * Date filters to apply to the product tags' `updated_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() updated_at?: DateComparisonOperator + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string + /** + * Filter product tags by the ID of their associated discount condition. + */ @IsString() @IsOptional() discount_condition_id?: string diff --git a/packages/medusa/src/api/routes/store/product-types/list-product-types.ts b/packages/medusa/src/api/routes/store/product-types/list-product-types.ts index 3fcaf70fde..8c1c6e3c3c 100644 --- a/packages/medusa/src/api/routes/store/product-types/list-product-types.ts +++ b/packages/medusa/src/api/routes/store/product-types/list-product-types.ts @@ -95,7 +95,7 @@ import ProductTypeService from "../../../../services/product-type" * medusa.productTypes.list() * .then(({ product_types }) => { * console.log(product_types.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -146,32 +146,56 @@ export default async (req, res) => { }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product types. + */ // eslint-disable-next-line max-len export class StoreGetProductTypesParams extends FindPaginationParams { + /** + * IDs to filter product types by. + */ @IsType([String, [String], StringComparisonOperator]) @IsOptional() id?: string | string[] | StringComparisonOperator + /** + * Search term to search product types' values. + */ @IsString() @IsOptional() q?: string + /** + * Values to filter product types by. + */ @IsType([String, [String], StringComparisonOperator]) @IsOptional() value?: string | string[] | StringComparisonOperator + /** + * Date filters to apply on the product types' `created_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() created_at?: DateComparisonOperator + /** + * Date filters to apply on the product types' `updated_at` date. + */ @IsType([DateComparisonOperator]) @IsOptional() updated_at?: DateComparisonOperator + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string + /** + * Filter product types by the ID of their associated discount condition. + */ @IsString() @IsOptional() discount_condition_id?: string diff --git a/packages/medusa/src/api/routes/store/products/get-product.ts b/packages/medusa/src/api/routes/store/products/get-product.ts index eb18f58e2c..b5eb0776b1 100644 --- a/packages/medusa/src/api/routes/store/products/get-product.ts +++ b/packages/medusa/src/api/routes/store/products/get-product.ts @@ -55,7 +55,7 @@ import { defaultStoreProductRemoteQueryObject } from "./index" * medusa.products.retrieve(productId) * .then(({ product }) => { * console.log(product.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/products/index.ts b/packages/medusa/src/api/routes/store/products/index.ts index 7f0fa7c62d..ae07e8f908 100644 --- a/packages/medusa/src/api/routes/store/products/index.ts +++ b/packages/medusa/src/api/routes/store/products/index.ts @@ -233,6 +233,7 @@ export type StoreProductsRes = { /** * @schema StorePostSearchRes + * description: "The list of search results." * allOf: * - type: object * required: @@ -250,6 +251,7 @@ export type StorePostSearchRes = { /** * @schema StoreProductsListRes * type: object + * description: "The list of products with pagination fields." * x-expanded-relations: * field: products * relations: diff --git a/packages/medusa/src/api/routes/store/products/list-products.ts b/packages/medusa/src/api/routes/store/products/list-products.ts index f47d302c09..1be1036da9 100644 --- a/packages/medusa/src/api/routes/store/products/list-products.ts +++ b/packages/medusa/src/api/routes/store/products/list-products.ts @@ -188,7 +188,7 @@ import { promiseAll } from "@medusajs/utils" * medusa.products.list() * .then(({ products, limit, offset, count }) => { * console.log(products.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -414,77 +414,138 @@ async function listAndCountProductWithIsolatedProductModule( return [products, count] } +/** + * {@inheritDoc FindPaginationParams} + */ export class StoreGetProductsPaginationParams extends PriceSelectionParams { + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset?: number = 0 + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 100 + */ @IsNumber() @IsOptional() @Type(() => Number) limit?: number = 100 + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ @IsString() @IsOptional() order?: string } +/** + * Parameters used to filter and configure the pagination of the retrieved products. + */ export class StoreGetProductsParams extends StoreGetProductsPaginationParams { + /** + * {@inheritDoc FilterableProductProps.id} + */ @IsOptional() @IsType([String, [String]]) id?: string | string[] + /** + * {@inheritDoc FilterableProductProps.q} + */ @IsString() @IsOptional() q?: string + /** + * {@inheritDoc FilterableProductProps.collection_id} + */ @IsArray() @IsOptional() collection_id?: string[] + /** + * {@inheritDoc FilterableProductProps.tags} + */ @IsArray() @IsOptional() tags?: string[] + /** + * {@inheritDoc FilterableProductProps.title} + */ @IsString() @IsOptional() title?: string + /** + * {@inheritDoc FilterableProductProps.description} + */ @IsString() @IsOptional() description?: string + /** + * {@inheritDoc FilterableProductProps.handle} + */ @IsString() @IsOptional() handle?: string + /** + * {@inheritDoc FilterableProductProps.is_giftcard} + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value.toLowerCase())) is_giftcard?: boolean + /** + * {@inheritDoc FilterableProductProps.type_id} + */ @IsArray() @IsOptional() type_id?: string[] + /** + * {@inheritDoc FilterableProductProps.sales_channel_id} + */ @FeatureFlagDecorators(SalesChannelFeatureFlag.key, [IsOptional(), IsArray()]) sales_channel_id?: string[] + /** + * {@inheritDoc FilterableProductProps.category_id} + */ @IsArray() @IsOptional() category_id?: string[] + /** + * {@inheritDoc FilterableProductProps.include_category_children} + * + * @featureFlag product_categories + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value.toLowerCase())) include_category_children?: boolean + /** + * {@inheritDoc FilterableProductProps.created_at} + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * {@inheritDoc FilterableProductProps.created_at} + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/api/routes/store/products/search.ts b/packages/medusa/src/api/routes/store/products/search.ts index 142942478b..213a1ccb6d 100644 --- a/packages/medusa/src/api/routes/store/products/search.ts +++ b/packages/medusa/src/api/routes/store/products/search.ts @@ -29,7 +29,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ hits }) => { * console.log(hits.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/regions/get-region.ts b/packages/medusa/src/api/routes/store/regions/get-region.ts index d405af291c..3719c9bf3b 100644 --- a/packages/medusa/src/api/routes/store/regions/get-region.ts +++ b/packages/medusa/src/api/routes/store/regions/get-region.ts @@ -19,7 +19,7 @@ import { defaultRelations } from "." * medusa.regions.retrieve(regionId) * .then(({ region }) => { * console.log(region.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/regions/index.ts b/packages/medusa/src/api/routes/store/regions/index.ts index dea5f5dca4..958d2828ff 100644 --- a/packages/medusa/src/api/routes/store/regions/index.ts +++ b/packages/medusa/src/api/routes/store/regions/index.ts @@ -23,6 +23,7 @@ export const defaultRelations = [ /** * @schema StoreRegionsListRes * type: object + * description: "The list of regions with pagination fields." * x-expanded-relations: * field: regions * relations: @@ -57,6 +58,7 @@ export type StoreRegionsListRes = PaginatedResponse & { /** * @schema StoreRegionsRes * type: object + * description: "The region's details." * x-expanded-relations: * field: region * relations: diff --git a/packages/medusa/src/api/routes/store/regions/list-regions.ts b/packages/medusa/src/api/routes/store/regions/list-regions.ts index 0a3a120f26..44b95f9f5a 100644 --- a/packages/medusa/src/api/routes/store/regions/list-regions.ts +++ b/packages/medusa/src/api/routes/store/regions/list-regions.ts @@ -73,9 +73,9 @@ import { validator } from "../../../../utils/validator" * import Medusa from "@medusajs/medusa-js" * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) * medusa.regions.list() - * .then(({ regions }) => { + * .then(({ regions, count, limit, offset }) => { * console.log(regions.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts b/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts index 6ff05dc0d1..3eec6a4342 100644 --- a/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts +++ b/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts @@ -22,7 +22,7 @@ import ReturnReasonService from "../../../../services/return-reason" * medusa.returnReasons.retrieve(reasonId) * .then(({ return_reason }) => { * console.log(return_reason.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/return-reasons/index.ts b/packages/medusa/src/api/routes/store/return-reasons/index.ts index 36cadf3bee..28a8cd3769 100644 --- a/packages/medusa/src/api/routes/store/return-reasons/index.ts +++ b/packages/medusa/src/api/routes/store/return-reasons/index.ts @@ -39,6 +39,7 @@ export const defaultStoreReturnReasonRelations: (keyof ReturnReason)[] = [ /** * @schema StoreReturnReasonsListRes * type: object + * description: "The list of return reasons." * x-expanded-relations: * field: return_reasons * relations: @@ -60,6 +61,7 @@ export type StoreReturnReasonsListRes = { /** * @schema StoreReturnReasonsRes * type: object + * description: "The return reason's details." * x-expanded-relations: * field: return_reason * relations: diff --git a/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts b/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts index 176a18d09e..a8a7ec945c 100644 --- a/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts +++ b/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts @@ -20,7 +20,7 @@ import ReturnReasonService from "../../../../services/return-reason" * medusa.returnReasons.list() * .then(({ return_reasons }) => { * console.log(return_reasons.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/returns/create-return.ts b/packages/medusa/src/api/routes/store/returns/create-return.ts index 67ce04fc18..91069ab1b7 100644 --- a/packages/medusa/src/api/routes/store/returns/create-return.ts +++ b/packages/medusa/src/api/routes/store/returns/create-return.ts @@ -49,7 +49,7 @@ import { defaultRelations } from "." * }) * .then((data) => { * console.log(data.return.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/returns/index.ts b/packages/medusa/src/api/routes/store/returns/index.ts index 472d54527c..3a7c84d684 100644 --- a/packages/medusa/src/api/routes/store/returns/index.ts +++ b/packages/medusa/src/api/routes/store/returns/index.ts @@ -17,6 +17,7 @@ export const defaultRelations = ["items", "items.reason"] /** * @schema StoreReturnsRes * type: object + * description: "The return's details." * x-expanded-relations: * field: return * relations: diff --git a/packages/medusa/src/api/routes/store/shipping-options/index.ts b/packages/medusa/src/api/routes/store/shipping-options/index.ts index 627a869483..ff813bd7a2 100644 --- a/packages/medusa/src/api/routes/store/shipping-options/index.ts +++ b/packages/medusa/src/api/routes/store/shipping-options/index.ts @@ -21,6 +21,7 @@ export const defaultRelations = ["requirements"] /** * @schema StoreShippingOptionsListRes * type: object + * description: "The list of shipping options." * x-expanded-relations: * field: shipping_options * relations: diff --git a/packages/medusa/src/api/routes/store/shipping-options/list-options.ts b/packages/medusa/src/api/routes/store/shipping-options/list-options.ts index 0313d5dfdf..949644e688 100644 --- a/packages/medusa/src/api/routes/store/shipping-options/list-options.ts +++ b/packages/medusa/src/api/routes/store/shipping-options/list-options.ts @@ -31,7 +31,7 @@ import { validator } from "../../../../utils/validator" * medusa.shippingOptions.list() * .then(({ shipping_options }) => { * console.log(shipping_options.length); - * }); + * }) * - lang: Shell * label: cURL * source: | @@ -108,15 +108,27 @@ export default async (req, res) => { res.status(200).json({ shipping_options: data }) } +/** + * Filters to apply on the retrieved shipping options. + */ export class StoreGetShippingOptionsParams { + /** + * Product ID that is used to filter shipping options by whether they can be used to ship that product. + */ @IsOptional() @IsString() product_ids?: string + /** + * Filter the shipping options by the ID of their associated region. + */ @IsOptional() @IsString() region_id?: string + /** + * Filter the shipping options by whether they're return shipping options. + */ @IsOptional() @IsBooleanString() is_return?: string diff --git a/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts b/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts index d6cc59cf04..c7219e8a1f 100644 --- a/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts +++ b/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts @@ -22,7 +22,7 @@ import ShippingProfileService from "../../../../services/shipping-profile" * medusa.shippingOptions.listCartOptions(cartId) * .then(({ shipping_options }) => { * console.log(shipping_options.length); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/swaps/create-swap.ts b/packages/medusa/src/api/routes/store/swaps/create-swap.ts index 97d4a8584e..dd2260bdc6 100644 --- a/packages/medusa/src/api/routes/store/swaps/create-swap.ts +++ b/packages/medusa/src/api/routes/store/swaps/create-swap.ts @@ -62,7 +62,7 @@ import { validator } from "../../../../utils/validator" * }) * .then(({ swap }) => { * console.log(swap.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts b/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts index e44bd53386..26a4225430 100644 --- a/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts +++ b/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts @@ -19,7 +19,7 @@ import { defaultStoreSwapRelations } from "." * medusa.swaps.retrieveByCartId(cartId) * .then(({ swap }) => { * console.log(swap.id); - * }); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/swaps/index.ts b/packages/medusa/src/api/routes/store/swaps/index.ts index f2571b143a..0ede0c94fb 100644 --- a/packages/medusa/src/api/routes/store/swaps/index.ts +++ b/packages/medusa/src/api/routes/store/swaps/index.ts @@ -51,6 +51,7 @@ export const defaultStoreSwapFields: FindConfig["select"] = [ /** * @schema StoreSwapsRes * type: object + * description: "The swap's details." * x-expanded-relations: * field: swap * relations: diff --git a/packages/medusa/src/api/routes/store/variants/get-variant.ts b/packages/medusa/src/api/routes/store/variants/get-variant.ts index 4b546e8edd..bdaa57ba78 100644 --- a/packages/medusa/src/api/routes/store/variants/get-variant.ts +++ b/packages/medusa/src/api/routes/store/variants/get-variant.ts @@ -43,6 +43,16 @@ import { promiseAll } from "@medusajs/utils" * method: retrieve * queryParams: StoreGetVariantsVariantParams * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.product.variants.retrieve(productVariantId) + * .then(({ variant }) => { + * console.log(variant.id); + * }) * - lang: Shell * label: cURL * source: | diff --git a/packages/medusa/src/api/routes/store/variants/index.ts b/packages/medusa/src/api/routes/store/variants/index.ts index 5211fe481c..21dbfeaf11 100644 --- a/packages/medusa/src/api/routes/store/variants/index.ts +++ b/packages/medusa/src/api/routes/store/variants/index.ts @@ -48,6 +48,7 @@ export const allowedStoreVariantRelations = [ /** * @schema StoreVariantsRes * type: object + * description: "The product variant's details." * x-expanded-relations: * field: variant * relations: @@ -70,6 +71,7 @@ export type StoreVariantsRes = { /** * @schema StoreVariantsListRes * type: object + * description: "The list of product variants." * x-expanded-relations: * field: variants * relations: @@ -93,4 +95,3 @@ export type StoreVariantsListRes = { export * from "./get-variant" export * from "./list-variants" - diff --git a/packages/medusa/src/api/routes/store/variants/list-variants.ts b/packages/medusa/src/api/routes/store/variants/list-variants.ts index a2ddf6896d..ce867f96af 100644 --- a/packages/medusa/src/api/routes/store/variants/list-variants.ts +++ b/packages/medusa/src/api/routes/store/variants/list-variants.ts @@ -101,6 +101,16 @@ import { promiseAll } from "@medusajs/utils" * method: list * queryParams: StoreGetVariantsParams * x-codeSamples: + * - lang: JavaScript + * label: JS Client + * source: | + * import Medusa from "@medusajs/medusa-js" + * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) + * // must be previously logged in or use api token + * medusa.product.variants.list() + * .then(({ variants }) => { + * console.log(variants.length); + * }) * - lang: Shell * label: cURL * source: | @@ -195,33 +205,59 @@ export default async (req, res) => { res.json({ variants }) } +/** + * Parameters used to filter and configure the pagination of the retrieved product variants. + */ export class StoreGetVariantsParams extends PriceSelectionParams { + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 100 + */ @IsOptional() @IsInt() @Type(() => Number) limit?: number = 100 + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsOptional() @IsInt() @Type(() => Number) offset?: number = 0 + /** + * ID to filter the product variants by. + */ @IsOptional() @IsString() ids?: string + /** + * Filter product variants by the ID of their associated sales channel. + */ @IsOptional() @IsString() sales_channel_id?: string + /** + * IDs to filter product variants by. + */ @IsOptional() @IsType([String, [String]]) id?: string | string[] + /** + * Titles to filter product variants by. + */ @IsOptional() @IsType([String, [String]]) title?: string | string[] + /** + * Number filters to apply on the product variants' `inventory_quantity` field. + */ @IsOptional() @IsType([Number, NumericalComparisonOperator]) inventory_quantity?: number | NumericalComparisonOperator diff --git a/packages/medusa/src/models/address.ts b/packages/medusa/src/models/address.ts index ce95164387..adee784c67 100644 --- a/packages/medusa/src/models/address.ts +++ b/packages/medusa/src/models/address.ts @@ -60,6 +60,9 @@ export class Address extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "addr") diff --git a/packages/medusa/src/models/analytics-config.ts b/packages/medusa/src/models/analytics-config.ts index 0229f84ece..11f99f45bd 100644 --- a/packages/medusa/src/models/analytics-config.ts +++ b/packages/medusa/src/models/analytics-config.ts @@ -16,6 +16,9 @@ export class AnalyticsConfig extends SoftDeletableEntity { @Column({ default: false }) anonymize: boolean + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "acfg") diff --git a/packages/medusa/src/models/batch-job.ts b/packages/medusa/src/models/batch-job.ts index 1f8d736aa3..da86551047 100644 --- a/packages/medusa/src/models/batch-job.ts +++ b/packages/medusa/src/models/batch-job.ts @@ -66,6 +66,9 @@ export class BatchJob extends SoftDeletableEntity { status: BatchJobStatus + /** + * @apiIgnore + */ @AfterLoad() loadStatus(): void { /* Always keep the status order consistent. */ @@ -91,6 +94,9 @@ export class BatchJob extends SoftDeletableEntity { this.status = this.status ?? BatchJobStatus.CREATED } + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "batch") diff --git a/packages/medusa/src/models/cart.ts b/packages/medusa/src/models/cart.ts index cd7147f52d..cc42b8aadb 100644 --- a/packages/medusa/src/models/cart.ts +++ b/packages/medusa/src/models/cart.ts @@ -272,6 +272,9 @@ export enum CartType { @Entity() export class Cart extends SoftDeletableEntity { + /** + * @apiIgnore + */ readonly object = "cart" @Column({ nullable: true }) @@ -406,6 +409,9 @@ export class Cart extends SoftDeletableEntity { gift_card_total?: number gift_card_tax_total?: number + /** + * @apiIgnore + */ @AfterLoad() private afterLoad(): void { if (this.payment_sessions) { @@ -413,6 +419,9 @@ export class Cart extends SoftDeletableEntity { } } + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "cart") diff --git a/packages/medusa/src/models/claim-image.ts b/packages/medusa/src/models/claim-image.ts index 6d22b898b5..f1b40e1f82 100644 --- a/packages/medusa/src/models/claim-image.ts +++ b/packages/medusa/src/models/claim-image.ts @@ -28,6 +28,9 @@ export class ClaimImage extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "cimg") diff --git a/packages/medusa/src/models/claim-item.ts b/packages/medusa/src/models/claim-item.ts index 8deeb347b6..a4888f66ec 100644 --- a/packages/medusa/src/models/claim-item.ts +++ b/packages/medusa/src/models/claim-item.ts @@ -83,6 +83,9 @@ export class ClaimItem extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "citm") diff --git a/packages/medusa/src/models/claim-order.ts b/packages/medusa/src/models/claim-order.ts index b0e68316ce..67ea2427ab 100644 --- a/packages/medusa/src/models/claim-order.ts +++ b/packages/medusa/src/models/claim-order.ts @@ -23,26 +23,83 @@ import { ShippingMethod } from "./shipping-method" import { SoftDeletableEntity } from "../interfaces/models/soft-deletable-entity" import { generateEntityId } from "../utils/generate-entity-id" +/** + * @enum + * + * The claim's type. + */ export enum ClaimType { + /** + * The claim refunds an amount to the customer. + */ REFUND = "refund", + /** + * The claim replaces the returned item with a new one. + */ REPLACE = "replace", } +/** + * @enum + * + * The claim's payment status + */ export enum ClaimPaymentStatus { + /** + * The payment status isn't set, which is typically used when the claim's type is `replace`. + */ NA = "na", + /** + * The payment isn't refunded. + */ NOT_REFUNDED = "not_refunded", + /** + * The payment is refunded. + */ REFUNDED = "refunded", } +/** + * @enum + * + * The claim's fulfillment status. + */ export enum ClaimFulfillmentStatus { + /** + * The claim's replacement items are not fulfilled. + */ NOT_FULFILLED = "not_fulfilled", + /** + * Some of the claim's replacement items, but not all, are fulfilled. + */ PARTIALLY_FULFILLED = "partially_fulfilled", + /** + * The claim's replacement items are fulfilled. + */ FULFILLED = "fulfilled", + /** + * Some of the claim's replacement items, but not all, are shipped. + */ PARTIALLY_SHIPPED = "partially_shipped", + /** + * The claim's replacement items are shipped. + */ SHIPPED = "shipped", + /** + * Some of the claim's items, but not all, are returned. + */ PARTIALLY_RETURNED = "partially_returned", + /** + * The claim's items are returned. + */ RETURNED = "returned", + /** + * The claim's fulfillments are canceled. + */ CANCELED = "canceled", + /** + * The claim's fulfillment requires action. + */ REQUIRES_ACTION = "requires_action", } @@ -124,6 +181,9 @@ export class ClaimOrder extends SoftDeletableEntity { @Column({ nullable: true }) idempotency_key: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "claim") diff --git a/packages/medusa/src/models/claim-tag.ts b/packages/medusa/src/models/claim-tag.ts index 0171a8f6a9..db6ed3fa41 100644 --- a/packages/medusa/src/models/claim-tag.ts +++ b/packages/medusa/src/models/claim-tag.ts @@ -13,6 +13,9 @@ export class ClaimTag extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ctag") diff --git a/packages/medusa/src/models/custom-shipping-option.ts b/packages/medusa/src/models/custom-shipping-option.ts index a4153f1e4e..f0bd6e2c5e 100644 --- a/packages/medusa/src/models/custom-shipping-option.ts +++ b/packages/medusa/src/models/custom-shipping-option.ts @@ -39,6 +39,9 @@ export class CustomShippingOption extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "cso") diff --git a/packages/medusa/src/models/customer-group.ts b/packages/medusa/src/models/customer-group.ts index 9cfbdcd634..3f9ad2c230 100644 --- a/packages/medusa/src/models/customer-group.ts +++ b/packages/medusa/src/models/customer-group.ts @@ -25,6 +25,9 @@ export class CustomerGroup extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "cgrp") diff --git a/packages/medusa/src/models/customer.ts b/packages/medusa/src/models/customer.ts index ab584cd198..ef63794871 100644 --- a/packages/medusa/src/models/customer.ts +++ b/packages/medusa/src/models/customer.ts @@ -42,6 +42,9 @@ export class Customer extends SoftDeletableEntity { @OneToMany(() => Address, (address) => address.customer) shipping_addresses: Address[] + /** + * @apiIgnore + */ @Column({ nullable: true, select: false }) password_hash: string @@ -73,6 +76,9 @@ export class Customer extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "cus") diff --git a/packages/medusa/src/models/discount-condition.ts b/packages/medusa/src/models/discount-condition.ts index b32679e322..1c83014288 100644 --- a/packages/medusa/src/models/discount-condition.ts +++ b/packages/medusa/src/models/discount-condition.ts @@ -22,16 +22,47 @@ import { SoftDeletableEntity } from "../interfaces/models/soft-deletable-entity" import { generateEntityId } from "../utils/generate-entity-id" import { Discount } from "./discount" +/** + * @enum + * + * The discount condition's type. + */ export enum DiscountConditionType { + /** + * The discount condition is used for products. + */ PRODUCTS = "products", + /** + * The discount condition is used for product types. + */ PRODUCT_TYPES = "product_types", + /** + * The discount condition is used for product collections. + */ PRODUCT_COLLECTIONS = "product_collections", + /** + * The discount condition is used for product tags. + */ PRODUCT_TAGS = "product_tags", + /** + * The discount condition is used for customer groups. + */ CUSTOMER_GROUPS = "customer_groups", } +/** + * @enum + * + * The possible operators used for a discount condition. + */ export enum DiscountConditionOperator { + /** + * The discountable resources are within the specified resources. + */ IN = "in", + /** + * The discountable resources are everything but the specified resources. + */ NOT_IN = "not_in", } @@ -131,6 +162,9 @@ export class DiscountCondition extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "discon") @@ -167,8 +201,9 @@ export class DiscountCondition extends SoftDeletableEntity { * - product_tags * - customer_groups * operator: - * description: "The operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that - * discountable resources are everything but the specified resources." + * description: >- + * The operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that + * discountable resources are everything but the specified resources. * type: string * enum: * - in diff --git a/packages/medusa/src/models/discount-rule.ts b/packages/medusa/src/models/discount-rule.ts index 112c362109..305cb7c3c8 100644 --- a/packages/medusa/src/models/discount-rule.ts +++ b/packages/medusa/src/models/discount-rule.ts @@ -5,14 +5,39 @@ import { DiscountCondition } from "./discount-condition" import { SoftDeletableEntity } from "../interfaces/models/soft-deletable-entity" import { generateEntityId } from "../utils/generate-entity-id" +/** + * @enum + * + * The possible types of discount rules. + */ export enum DiscountRuleType { + /** + * Discounts that reduce the price by a fixed amount. + */ FIXED = "fixed", + /** + * Discounts that reduce the price by a percentage reduction. + */ PERCENTAGE = "percentage", + /** + * Discounts that sets the shipping price to `0`. + */ FREE_SHIPPING = "free_shipping", } +/** + * @enum + * + * The scope that the discount should apply to. + */ export enum AllocationType { + /** + * The discount should be applied to the checkout total. + */ TOTAL = "total", + /** + * The discount should be applied to applicable items in the cart. + */ ITEM = "item", } @@ -43,6 +68,9 @@ export class DiscountRule extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "dru") @@ -70,7 +98,8 @@ export class DiscountRule extends SoftDeletableEntity { * type: string * example: dru_01F0YESMVK96HVX7N419E3CJ7C * type: - * description: The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers. + * description: >- + * The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers. * type: string * enum: * - fixed diff --git a/packages/medusa/src/models/discount.ts b/packages/medusa/src/models/discount.ts index 1a827d8cff..5cfb9d04d8 100644 --- a/packages/medusa/src/models/discount.ts +++ b/packages/medusa/src/models/discount.ts @@ -77,6 +77,9 @@ export class Discount extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private upperCaseCodeAndTrim(): void { this.code = this.code.toUpperCase().trim() diff --git a/packages/medusa/src/models/draft-order.ts b/packages/medusa/src/models/draft-order.ts index 45ab0c176d..43b3a7f703 100644 --- a/packages/medusa/src/models/draft-order.ts +++ b/packages/medusa/src/models/draft-order.ts @@ -18,8 +18,19 @@ import { manualAutoIncrement } from "../utils/manual-auto-increment" import { Cart } from "./cart" import { Order } from "./order" +/** + * @enum + * + * The draft order's status. + */ export enum DraftOrderStatus { + /** + * The draft order is open. + */ OPEN = "open", + /** + * The draft order is completed, and an order has been created from it. + */ COMPLETED = "completed", } @@ -64,6 +75,9 @@ export class DraftOrder extends BaseEntity { @Column({ nullable: true }) idempotency_key: string + /** + * @apiIgnore + */ @BeforeInsert() private async beforeInsert(): Promise { this.id = generateEntityId(this.id, "dorder") diff --git a/packages/medusa/src/models/fulfillment.ts b/packages/medusa/src/models/fulfillment.ts index a83d03cbd9..9fd0552934 100644 --- a/packages/medusa/src/models/fulfillment.ts +++ b/packages/medusa/src/models/fulfillment.ts @@ -87,6 +87,9 @@ export class Fulfillment extends BaseEntity { @Column({ nullable: true }) idempotency_key: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ful") diff --git a/packages/medusa/src/models/gift-card-transaction.ts b/packages/medusa/src/models/gift-card-transaction.ts index b3db0eb44d..6eba382071 100644 --- a/packages/medusa/src/models/gift-card-transaction.ts +++ b/packages/medusa/src/models/gift-card-transaction.ts @@ -48,6 +48,9 @@ export class GiftCardTransaction { @Column({ type: "real", nullable: true }) tax_rate: number | null + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "gct") diff --git a/packages/medusa/src/models/gift-card.ts b/packages/medusa/src/models/gift-card.ts index 4896210ce4..1ef5a00fbf 100644 --- a/packages/medusa/src/models/gift-card.ts +++ b/packages/medusa/src/models/gift-card.ts @@ -56,6 +56,9 @@ export class GiftCard extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "gift") diff --git a/packages/medusa/src/models/idempotency-key.ts b/packages/medusa/src/models/idempotency-key.ts index d9fbb08542..437389cee0 100644 --- a/packages/medusa/src/models/idempotency-key.ts +++ b/packages/medusa/src/models/idempotency-key.ts @@ -43,6 +43,9 @@ export class IdempotencyKey { @Column({ default: "started" }) recovery_point: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ikey") diff --git a/packages/medusa/src/models/image.ts b/packages/medusa/src/models/image.ts index 58ea5236cc..31f13005f4 100644 --- a/packages/medusa/src/models/image.ts +++ b/packages/medusa/src/models/image.ts @@ -12,6 +12,9 @@ export class Image extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "img") diff --git a/packages/medusa/src/models/invite.ts b/packages/medusa/src/models/invite.ts index 2bf43c380b..5dcfe49a9a 100644 --- a/packages/medusa/src/models/invite.ts +++ b/packages/medusa/src/models/invite.ts @@ -31,6 +31,9 @@ export class Invite extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "invite") diff --git a/packages/medusa/src/models/line-item-adjustment.ts b/packages/medusa/src/models/line-item-adjustment.ts index d3bfa91ed7..fceac7fab4 100644 --- a/packages/medusa/src/models/line-item-adjustment.ts +++ b/packages/medusa/src/models/line-item-adjustment.ts @@ -46,6 +46,9 @@ export class LineItemAdjustment { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "lia") diff --git a/packages/medusa/src/models/line-item-tax-line.ts b/packages/medusa/src/models/line-item-tax-line.ts index 31fe76e241..a784550267 100644 --- a/packages/medusa/src/models/line-item-tax-line.ts +++ b/packages/medusa/src/models/line-item-tax-line.ts @@ -23,6 +23,9 @@ export class LineItemTaxLine extends TaxLine { @JoinColumn({ name: "item_id" }) item: LineItem + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "litl") diff --git a/packages/medusa/src/models/line-item.ts b/packages/medusa/src/models/line-item.ts index 405fbc9865..ef4bfc385b 100644 --- a/packages/medusa/src/models/line-item.ts +++ b/packages/medusa/src/models/line-item.ts @@ -162,6 +162,9 @@ export class LineItem extends BaseEntity { raw_discount_total?: number | null gift_card_total?: number | null + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "item") @@ -178,6 +181,9 @@ export class LineItem extends BaseEntity { } } + /** + * @apiIgnore + */ @FeatureFlagDecorators(IsolateProductDomain.key, [BeforeUpdate()]) beforeUpdate(): void { if ( @@ -189,6 +195,9 @@ export class LineItem extends BaseEntity { } } + /** + * @apiIgnore + */ @FeatureFlagDecorators(IsolateProductDomain.key, [AfterLoad(), AfterUpdate()]) afterUpdateOrLoad(): void { if (this.variant) { diff --git a/packages/medusa/src/models/money-amount.ts b/packages/medusa/src/models/money-amount.ts index 3c630ef0c0..db172c17d9 100644 --- a/packages/medusa/src/models/money-amount.ts +++ b/packages/medusa/src/models/money-amount.ts @@ -75,6 +75,9 @@ export class MoneyAmount extends SoftDeletableEntity { @JoinColumn({ name: "region_id" }) region?: Region + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): undefined | void { this.id = generateEntityId(this.id, "ma") @@ -86,6 +89,9 @@ export class MoneyAmount extends SoftDeletableEntity { } } + /** + * @apiIgnore + */ @BeforeUpdate() private beforeUpdate(): void { if (this.variant || this.variant_id) { @@ -95,6 +101,9 @@ export class MoneyAmount extends SoftDeletableEntity { } } + /** + * @apiIgnore + */ @AfterLoad() private afterLoad() { this.variant = this.variants?.[0] diff --git a/packages/medusa/src/models/note.ts b/packages/medusa/src/models/note.ts index 36b8c996db..42bd7ddcd8 100644 --- a/packages/medusa/src/models/note.ts +++ b/packages/medusa/src/models/note.ts @@ -35,6 +35,9 @@ export class Note extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "note") diff --git a/packages/medusa/src/models/notification.ts b/packages/medusa/src/models/notification.ts index e002fddb94..a46c72efdc 100644 --- a/packages/medusa/src/models/notification.ts +++ b/packages/medusa/src/models/notification.ts @@ -58,6 +58,9 @@ export class Notification extends BaseEntity { @JoinColumn({ name: "provider_id" }) provider: NotificationProvider + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "noti") diff --git a/packages/medusa/src/models/oauth.ts b/packages/medusa/src/models/oauth.ts index f91d3677f5..2ac0c610ed 100644 --- a/packages/medusa/src/models/oauth.ts +++ b/packages/medusa/src/models/oauth.ts @@ -24,6 +24,9 @@ export class Oauth { @DbAwareColumn({ type: "jsonb", nullable: true }) data: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "oauth") diff --git a/packages/medusa/src/models/order-edit.ts b/packages/medusa/src/models/order-edit.ts index c9c53cb31c..50734e0a5c 100644 --- a/packages/medusa/src/models/order-edit.ts +++ b/packages/medusa/src/models/order-edit.ts @@ -16,11 +16,31 @@ import { resolveDbType } from "../utils/db-aware-column" import { LineItem, Order, OrderItemChange, PaymentCollection } from "." +/** + * @enum + * + * The order edit's status. + */ export enum OrderEditStatus { + /** + * The order edit is confirmed. + */ CONFIRMED = "confirmed", + /** + * The order edit is declined. + */ DECLINED = "declined", + /** + * The order edit is requested. + */ REQUESTED = "requested", + /** + * The order edit is created. + */ CREATED = "created", + /** + * The order edit is canceled. + */ CANCELED = "canceled", } @@ -96,11 +116,17 @@ export class OrderEdit extends BaseEntity { status: OrderEditStatus + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "oe") } + /** + * @apiIgnore + */ @AfterLoad() loadStatus(): void { if (this.requested_at) { diff --git a/packages/medusa/src/models/order-item-change.ts b/packages/medusa/src/models/order-item-change.ts index 93cbd8f9c5..1dcaabf775 100644 --- a/packages/medusa/src/models/order-item-change.ts +++ b/packages/medusa/src/models/order-item-change.ts @@ -14,9 +14,23 @@ import { DbAwareColumn } from "../utils/db-aware-column" import { LineItem } from "./line-item" import { OrderEdit } from "./order-edit" +/** + * @enum + * + * The type of the order edit item change. + */ export enum OrderEditItemChangeType { + /** + * A new item to be added to the original order. + */ ITEM_ADD = "item_add", + /** + * An existing item to be removed from the original order. + */ ITEM_REMOVE = "item_remove", + /** + * An existing item to be updated in the original order. + */ ITEM_UPDATE = "item_update", } @@ -51,6 +65,9 @@ export class OrderItemChange extends SoftDeletableEntity { @JoinColumn({ name: "line_item_id" }) line_item?: LineItem + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "oic") diff --git a/packages/medusa/src/models/order.ts b/packages/medusa/src/models/order.ts index 02d905886c..7891b53748 100644 --- a/packages/medusa/src/models/order.ts +++ b/packages/medusa/src/models/order.ts @@ -37,38 +37,121 @@ import { SalesChannel } from "./sales-channel" import { ShippingMethod } from "./shipping-method" import { Swap } from "./swap" +/** + * @enum + * + * The order's status. + */ export enum OrderStatus { + /** + * The order is pending. + */ PENDING = "pending", + /** + * The order is completed, meaning that + * the items have been fulfilled and the payment + * has been captured. + */ COMPLETED = "completed", + /** + * The order is archived. + */ ARCHIVED = "archived", + /** + * The order is canceled. + */ CANCELED = "canceled", + /** + * The order requires action. + */ REQUIRES_ACTION = "requires_action", } +/** + * @enum + * + * The order's fulfillment status. + */ export enum FulfillmentStatus { + /** + * The order's items are not fulfilled. + */ NOT_FULFILLED = "not_fulfilled", + /** + * Some of the order's items, but not all, are fulfilled. + */ PARTIALLY_FULFILLED = "partially_fulfilled", + /** + * The order's items are fulfilled. + */ FULFILLED = "fulfilled", + /** + * Some of the order's items, but not all, are shipped. + */ PARTIALLY_SHIPPED = "partially_shipped", + /** + * The order's items are shipped. + */ SHIPPED = "shipped", + /** + * Some of the order's items, but not all, are returned. + */ PARTIALLY_RETURNED = "partially_returned", + /** + * The order's items are returned. + */ RETURNED = "returned", + /** + * The order's fulfillments are canceled. + */ CANCELED = "canceled", + /** + * The order's fulfillment requires action. + */ REQUIRES_ACTION = "requires_action", } +/** + * @enum + * + * The order's payment status. + */ export enum PaymentStatus { + /** + * The order's payment is not paid. + */ NOT_PAID = "not_paid", + /** + * The order's payment is awaiting capturing. + */ AWAITING = "awaiting", + /** + * The order's payment is captured. + */ CAPTURED = "captured", + /** + * Some of the order's payment amount is refunded. + */ PARTIALLY_REFUNDED = "partially_refunded", + /** + * The order's payment amount is refunded. + */ REFUNDED = "refunded", + /** + * The order's payment is canceled. + */ CANCELED = "canceled", + /** + * The order's payment requires action. + */ REQUIRES_ACTION = "requires_action", } @Entity() export class Order extends BaseEntity { + /** + * @apiIgnore + */ readonly object = "order" @DbAwareColumn({ type: "enum", enum: OrderStatus, default: "pending" }) @@ -255,6 +338,9 @@ export class Order extends BaseEntity { returnable_items?: LineItem[] + /** + * @apiIgnore + */ @BeforeInsert() private async beforeInsert(): Promise { this.id = generateEntityId(this.id, "order") diff --git a/packages/medusa/src/models/payment-collection.ts b/packages/medusa/src/models/payment-collection.ts index b37ff6ba5a..02d7065266 100644 --- a/packages/medusa/src/models/payment-collection.ts +++ b/packages/medusa/src/models/payment-collection.ts @@ -14,15 +14,43 @@ import { SoftDeletableEntity } from "../interfaces/models/soft-deletable-entity" import { generateEntityId } from "../utils" import { DbAwareColumn } from "../utils/db-aware-column" +/** + * @enum + * + * The payment collection's status. + */ export enum PaymentCollectionStatus { + /** + * The payment collection isn't paid. + */ NOT_PAID = "not_paid", + /** + * The payment collection is awaiting payment. + */ AWAITING = "awaiting", + /** + * The payment colleciton is authorized. + */ AUTHORIZED = "authorized", + /** + * Some of the payments in the payment collection are authorized. + */ PARTIALLY_AUTHORIZED = "partially_authorized", + /** + * The payment collection is canceled. + */ CANCELED = "canceled", } +/** + * @enum + * + * The payment collection's type. + */ export enum PaymentCollectionType { + /** + * The payment collection is used for an order edit. + */ ORDER_EDIT = "order_edit", } @@ -93,6 +121,9 @@ export class PaymentCollection extends SoftDeletableEntity { @Column() created_by: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "paycol") @@ -158,7 +189,7 @@ export class PaymentCollection extends SoftDeletableEntity { * nullable: true * $ref: "#/components/schemas/Region" * currency_code: - * description: The 3 character ISO code for the currency this payment collection is associated with. + * description: The three character ISO code for the currency this payment collection is associated with. * type: string * example: usd * externalDocs: diff --git a/packages/medusa/src/models/payment-session.ts b/packages/medusa/src/models/payment-session.ts index 726badcf74..f2719b1a47 100644 --- a/packages/medusa/src/models/payment-session.ts +++ b/packages/medusa/src/models/payment-session.ts @@ -61,6 +61,9 @@ export class PaymentSession extends BaseEntity { @Column({ type: resolveDbType("timestamptz"), nullable: true }) payment_authorized_at: Date + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ps") diff --git a/packages/medusa/src/models/payment.ts b/packages/medusa/src/models/payment.ts index f597700be5..1f3e8258b6 100644 --- a/packages/medusa/src/models/payment.ts +++ b/packages/medusa/src/models/payment.ts @@ -80,6 +80,9 @@ export class Payment extends BaseEntity { @Column({ nullable: true }) idempotency_key: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "pay") diff --git a/packages/medusa/src/models/price-list.ts b/packages/medusa/src/models/price-list.ts index 6021c85bb9..b06f9adeca 100644 --- a/packages/medusa/src/models/price-list.ts +++ b/packages/medusa/src/models/price-list.ts @@ -63,6 +63,9 @@ export class PriceList extends SoftDeletableEntity { @FeatureFlagColumn(TaxInclusivePricingFeatureFlag.key, { default: false }) includes_tax: boolean + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): undefined | void { this.id = generateEntityId(this.id, "pl") diff --git a/packages/medusa/src/models/product-category.ts b/packages/medusa/src/models/product-category.ts index fc2d539ec3..2dee6af5cc 100644 --- a/packages/medusa/src/models/product-category.ts +++ b/packages/medusa/src/models/product-category.ts @@ -19,7 +19,13 @@ import { @Tree("materialized-path") @Index(["parent_category_id", "rank"], { unique: true }) export class ProductCategory extends BaseEntity { + /** + * @apiIgnore + */ static productCategoryProductJoinTable = "product_category_product" + /** + * @apiIgnore + */ static treeRelations = ["parent_category", "category_children"] @Column() @@ -72,6 +78,9 @@ export class ProductCategory extends BaseEntity { }) products: Product[] + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "pcat") @@ -109,6 +118,10 @@ export class ProductCategory extends BaseEntity { * description: The product category's name * type: string * example: Regular Fit + * description: + * description: The product category's description. + * type: string + * default: "" * handle: * description: A unique string that identifies the Product Category - can for example be used in slug structures. * type: string diff --git a/packages/medusa/src/models/product-collection.ts b/packages/medusa/src/models/product-collection.ts index 5d0cccb632..6384cad085 100644 --- a/packages/medusa/src/models/product-collection.ts +++ b/packages/medusa/src/models/product-collection.ts @@ -21,6 +21,9 @@ export class ProductCollection extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private createHandleIfNotProvided(): void { if (this.id) return diff --git a/packages/medusa/src/models/product-option-value.ts b/packages/medusa/src/models/product-option-value.ts index 2e2f2fc38c..6ae2faf55a 100644 --- a/packages/medusa/src/models/product-option-value.ts +++ b/packages/medusa/src/models/product-option-value.ts @@ -39,6 +39,9 @@ export class ProductOptionValue extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "optval") diff --git a/packages/medusa/src/models/product-option.ts b/packages/medusa/src/models/product-option.ts index 1b63360ac5..9564a90dd8 100644 --- a/packages/medusa/src/models/product-option.ts +++ b/packages/medusa/src/models/product-option.ts @@ -33,6 +33,9 @@ export class ProductOption extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "opt") diff --git a/packages/medusa/src/models/product-tag.ts b/packages/medusa/src/models/product-tag.ts index 273d554c3e..90446c9b3d 100644 --- a/packages/medusa/src/models/product-tag.ts +++ b/packages/medusa/src/models/product-tag.ts @@ -12,6 +12,9 @@ export class ProductTag extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ptag") diff --git a/packages/medusa/src/models/product-type.ts b/packages/medusa/src/models/product-type.ts index 2eabb10fc2..01390d4b36 100644 --- a/packages/medusa/src/models/product-type.ts +++ b/packages/medusa/src/models/product-type.ts @@ -12,6 +12,9 @@ export class ProductType extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ptyp") diff --git a/packages/medusa/src/models/product-variant-inventory-item.ts b/packages/medusa/src/models/product-variant-inventory-item.ts index c9029f5334..235fd951af 100644 --- a/packages/medusa/src/models/product-variant-inventory-item.ts +++ b/packages/medusa/src/models/product-variant-inventory-item.ts @@ -27,6 +27,9 @@ export class ProductVariantInventoryItem extends SoftDeletableEntity { @Column({ type: "int", default: 1 }) required_quantity: number + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "pvitem") diff --git a/packages/medusa/src/models/product-variant-money-amount.ts b/packages/medusa/src/models/product-variant-money-amount.ts index 75a82febae..ccef76427f 100644 --- a/packages/medusa/src/models/product-variant-money-amount.ts +++ b/packages/medusa/src/models/product-variant-money-amount.ts @@ -14,6 +14,9 @@ export class ProductVariantMoneyAmount extends SoftDeletableEntity { @Column() variant_id: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "pvma_") diff --git a/packages/medusa/src/models/product-variant.ts b/packages/medusa/src/models/product-variant.ts index 32b2f3f4d6..a9168a2edf 100644 --- a/packages/medusa/src/models/product-variant.ts +++ b/packages/medusa/src/models/product-variant.ts @@ -117,6 +117,9 @@ export class ProductVariant extends SoftDeletableEntity { purchasable?: boolean + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "variant") diff --git a/packages/medusa/src/models/product.ts b/packages/medusa/src/models/product.ts index 7ad68202a5..9fa72cd6ab 100644 --- a/packages/medusa/src/models/product.ts +++ b/packages/medusa/src/models/product.ts @@ -27,10 +27,27 @@ import { SoftDeletableEntity } from "../interfaces/models/soft-deletable-entity" import _ from "lodash" import { generateEntityId } from "../utils" +/** + * @enum + * + * The status of a product. + */ export enum ProductStatus { + /** + * The product is a draft. It's not viewable by customers. + */ DRAFT = "draft", + /** + * The product is proposed, but not yet published. + */ PROPOSED = "proposed", + /** + * The product is published. + */ PUBLISHED = "published", + /** + * The product is rejected. It's not viewable by customers. + */ REJECTED = "rejected", } @@ -191,6 +208,9 @@ export class Product extends SoftDeletableEntity { ]) sales_channels: SalesChannel[] + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "prod") @@ -204,6 +224,9 @@ export class Product extends SoftDeletableEntity { } } + /** + * @apiIgnore + */ @BeforeUpdate() private beforeUpdate(): void { if (this.profile_id) { @@ -211,6 +234,9 @@ export class Product extends SoftDeletableEntity { } } + /** + * @apiIgnore + */ @AfterLoad() private afterLoad(): void { if (this.profiles) { diff --git a/packages/medusa/src/models/publishable-api-key.ts b/packages/medusa/src/models/publishable-api-key.ts index 5dc4a46e71..d531fd55cf 100644 --- a/packages/medusa/src/models/publishable-api-key.ts +++ b/packages/medusa/src/models/publishable-api-key.ts @@ -17,6 +17,9 @@ export class PublishableApiKey extends BaseEntity { @Column() title: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "pk") diff --git a/packages/medusa/src/models/refund.ts b/packages/medusa/src/models/refund.ts index 0301e95913..2439589419 100644 --- a/packages/medusa/src/models/refund.ts +++ b/packages/medusa/src/models/refund.ts @@ -14,11 +14,31 @@ import { generateEntityId } from "../utils/generate-entity-id" import { Order } from "./order" import { Payment } from "./payment" +/** + * @enum + * + * The reason of the refund. + */ export enum RefundReason { + /** + * The refund is applied as a discount. + */ DISCOUNT = "discount", + /** + * The refund is applied because of a created return. + */ RETURN = "return", + /** + * The refund is applied because of a created swap. + */ SWAP = "swap", + /** + * The refund is applied because of a created claim. + */ CLAIM = "claim", + /** + * The refund is created for a custom reason. + */ OTHER = "other", } @@ -55,6 +75,9 @@ export class Refund extends BaseEntity { @Column({ nullable: true }) idempotency_key: string + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ref") diff --git a/packages/medusa/src/models/region.ts b/packages/medusa/src/models/region.ts index f36dcfcdcc..7ef3e58fc3 100644 --- a/packages/medusa/src/models/region.ts +++ b/packages/medusa/src/models/region.ts @@ -98,6 +98,9 @@ export class Region extends SoftDeletableEntity { @FeatureFlagColumn(TaxInclusivePricingFeatureFlag.key, { default: false }) includes_tax: boolean + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "reg") @@ -132,7 +135,7 @@ export class Region extends SoftDeletableEntity { * type: string * example: EU * currency_code: - * description: The 3 character currency code used in the region. + * description: The three character currency code used in the region. * type: string * example: usd * externalDocs: diff --git a/packages/medusa/src/models/return-reason.ts b/packages/medusa/src/models/return-reason.ts index 28590cd45d..b5cde80c4a 100644 --- a/packages/medusa/src/models/return-reason.ts +++ b/packages/medusa/src/models/return-reason.ts @@ -41,6 +41,9 @@ export class ReturnReason extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "rr") diff --git a/packages/medusa/src/models/return.ts b/packages/medusa/src/models/return.ts index 4533ac2ad2..b60aedb163 100644 --- a/packages/medusa/src/models/return.ts +++ b/packages/medusa/src/models/return.ts @@ -18,10 +18,27 @@ import { ReturnItem } from "./return-item" import { ShippingMethod } from "./shipping-method" import { Swap } from "./swap" +/** + * @enum + * + * The return's status. + */ export enum ReturnStatus { + /** + * The return is requested. + */ REQUESTED = "requested", + /** + * The return is received. + */ RECEIVED = "received", + /** + * The return is awaiting action. + */ REQUIRES_ACTION = "requires_action", + /** + * The return is canceled. + */ CANCELED = "canceled", } @@ -91,6 +108,9 @@ export class Return extends BaseEntity { @Column({ nullable: true, type: "text" }) idempotency_key: string | null + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "ret") diff --git a/packages/medusa/src/models/sales-channel-location.ts b/packages/medusa/src/models/sales-channel-location.ts index 21579a6f56..a7c92aabb7 100644 --- a/packages/medusa/src/models/sales-channel-location.ts +++ b/packages/medusa/src/models/sales-channel-location.ts @@ -19,6 +19,9 @@ export class SalesChannelLocation extends SoftDeletableEntity { @JoinColumn({ name: "sales_channel_id" }) sales_channel: SalesChannel + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "scloc") diff --git a/packages/medusa/src/models/sales-channel.ts b/packages/medusa/src/models/sales-channel.ts index 8c24881188..38b59a68b3 100644 --- a/packages/medusa/src/models/sales-channel.ts +++ b/packages/medusa/src/models/sales-channel.ts @@ -28,6 +28,9 @@ export class SalesChannel extends SoftDeletableEntity { ) locations: SalesChannelLocation[] + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "sc") diff --git a/packages/medusa/src/models/shipping-method-tax-line.ts b/packages/medusa/src/models/shipping-method-tax-line.ts index e5c31bb7a0..3ff62c0a83 100644 --- a/packages/medusa/src/models/shipping-method-tax-line.ts +++ b/packages/medusa/src/models/shipping-method-tax-line.ts @@ -23,6 +23,9 @@ export class ShippingMethodTaxLine extends TaxLine { @JoinColumn({ name: "shipping_method_id" }) shipping_method: ShippingMethod + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "smtl") diff --git a/packages/medusa/src/models/shipping-method.ts b/packages/medusa/src/models/shipping-method.ts index 910db350a0..3e551c60d7 100644 --- a/packages/medusa/src/models/shipping-method.ts +++ b/packages/medusa/src/models/shipping-method.ts @@ -98,6 +98,9 @@ export class ShippingMethod { total?: number tax_total?: number + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "sm") diff --git a/packages/medusa/src/models/shipping-option-requirement.ts b/packages/medusa/src/models/shipping-option-requirement.ts index ec44f4bab8..5a864d7bd8 100644 --- a/packages/medusa/src/models/shipping-option-requirement.ts +++ b/packages/medusa/src/models/shipping-option-requirement.ts @@ -13,8 +13,19 @@ import { DbAwareColumn, resolveDbType } from "../utils/db-aware-column" import { ShippingOption } from "./shipping-option" import { generateEntityId } from "../utils/generate-entity-id" +/** + * @enum + * + * The type of shipping option requirement. + */ export enum RequirementType { + /** + * The shipping option can only be applied if the subtotal is greater than the requirement's amount. + */ MIN_SUBTOTAL = "min_subtotal", + /** + * The shipping option can only be applied if the subtotal is less than the requirement's amont. + */ MAX_SUBTOTAL = "max_subtotal", } @@ -40,6 +51,9 @@ export class ShippingOptionRequirement { @DeleteDateColumn({ type: resolveDbType("timestamptz") }) deleted_at: Date + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "sor") diff --git a/packages/medusa/src/models/shipping-option.ts b/packages/medusa/src/models/shipping-option.ts index 83a75abb9d..57e535ab90 100644 --- a/packages/medusa/src/models/shipping-option.ts +++ b/packages/medusa/src/models/shipping-option.ts @@ -19,8 +19,19 @@ import { generateEntityId } from "../utils/generate-entity-id" import { FeatureFlagColumn } from "../utils/feature-flag-decorators" import TaxInclusivePricingFeatureFlag from "../loaders/feature-flags/tax-inclusive-pricing" +/** + * @enum + * + * The type of the shipping option price. + */ export enum ShippingOptionPriceType { + /** + * The shipping option's price is a flat rate. + */ FLAT_RATE = "flat_rate", + /** + * The shipping option's price is calculated. In this case, the `amount` field is typically `null`. + */ CALCULATED = "calculated", } @@ -80,6 +91,9 @@ export class ShippingOption extends SoftDeletableEntity { @FeatureFlagColumn(TaxInclusivePricingFeatureFlag.key, { default: false }) includes_tax: boolean + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "so") diff --git a/packages/medusa/src/models/shipping-profile.ts b/packages/medusa/src/models/shipping-profile.ts index 1237249a7d..3a8ba8fd8c 100644 --- a/packages/medusa/src/models/shipping-profile.ts +++ b/packages/medusa/src/models/shipping-profile.ts @@ -12,9 +12,23 @@ import { Product } from "./product" import { ShippingOption } from "./shipping-option" import { SoftDeletableEntity } from "../interfaces" +/** + * @enum + * + * The shipping profile's type. + */ export enum ShippingProfileType { + /** + * The default profile used to ship item. + */ DEFAULT = "default", + /** + * The profile used to ship gift cards. + */ GIFT_CARD = "gift_card", + /** + * The profile used to ship custom items. + */ CUSTOM = "custom", } @@ -46,6 +60,9 @@ export class ShippingProfile extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "sp") diff --git a/packages/medusa/src/models/staged-job.ts b/packages/medusa/src/models/staged-job.ts index 8f7c8f86e6..ac2810ec05 100644 --- a/packages/medusa/src/models/staged-job.ts +++ b/packages/medusa/src/models/staged-job.ts @@ -17,6 +17,9 @@ export class StagedJob { @DbAwareColumn({ type: "jsonb", default: {} }) options: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "job") diff --git a/packages/medusa/src/models/store.ts b/packages/medusa/src/models/store.ts index 3204fddb7f..dd92e72e28 100644 --- a/packages/medusa/src/models/store.ts +++ b/packages/medusa/src/models/store.ts @@ -69,6 +69,9 @@ export class Store extends BaseEntity { ]) default_sales_channel: SalesChannel + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "store") @@ -100,8 +103,9 @@ export class Store extends BaseEntity { * description: The name of the Store - this may be displayed to the Customer. * type: string * example: Medusa Store + * default: Medusa Store * default_currency_code: - * description: The 3 character currency code that is the default of the store. + * description: The three character currency code that is the default of the store. * type: string * example: usd * externalDocs: @@ -110,6 +114,7 @@ export class Store extends BaseEntity { * default_currency: * description: The details of the store's default currency. * x-expandable: "default_currency" + * default: "usd" * nullable: true * $ref: "#/components/schemas/Currency" * currencies: diff --git a/packages/medusa/src/models/swap.ts b/packages/medusa/src/models/swap.ts index 00a81b2753..671086c650 100644 --- a/packages/medusa/src/models/swap.ts +++ b/packages/medusa/src/models/swap.ts @@ -21,24 +21,79 @@ import { Payment } from "./payment" import { Return } from "./return" import { ShippingMethod } from "./shipping-method" +/** + * @enum + * + * The swap's fulfillment status. + */ export enum SwapFulfillmentStatus { + /** + * The swap's items aren't fulfilled. + */ NOT_FULFILLED = "not_fulfilled", + /** + * The swap's items are fulfilled. + */ FULFILLED = "fulfilled", + /** + * The swap's items are shipped. + */ SHIPPED = "shipped", + /** + * Some of the swap's items are shipped. + */ PARTIALLY_SHIPPED = "partially_shipped", + /** + * The swap's fulfillments are canceled. + */ CANCELED = "canceled", + /** + * The swap's fulfillments require an action. + */ REQUIRES_ACTION = "requires_action", } +/** + * @enum + * + * The swap's payment status. + */ export enum SwapPaymentStatus { + /** + * The swap's additional payment isn't paid. + */ NOT_PAID = "not_paid", + /** + * The swap is additional awaiting payment. + */ AWAITING = "awaiting", + /** + * The swap's additional payment is captured. + */ CAPTURED = "captured", + /** + * The swap's additional payment is confirmed. + */ CONFIRMED = "confirmed", + /** + * The swap's additional payment is canceled. + */ CANCELED = "canceled", + /** + * The negative difference amount between the returned item(s) and the new one(s) has been refuneded. + */ DIFFERENCE_REFUNDED = "difference_refunded", + /** + * Some of the negative difference amount between the returned item(s) and the new one(s) has been refuneded. + */ PARTIALLY_REFUNDED = "partially_refunded", + /** + * The amount in the associated order has been refunded. + */ REFUNDED = "refunded", + /** + * The swap's payment requires an action. + */ REQUIRES_ACTION = "requires_action", } @@ -112,6 +167,9 @@ export class Swap extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "swap") diff --git a/packages/medusa/src/models/tax-rate.ts b/packages/medusa/src/models/tax-rate.ts index 503b9a56c8..10e3aed40f 100644 --- a/packages/medusa/src/models/tax-rate.ts +++ b/packages/medusa/src/models/tax-rate.ts @@ -84,6 +84,9 @@ export class TaxRate extends BaseEntity { product_type_count?: number shipping_option_count?: number + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "txr") diff --git a/packages/medusa/src/models/tracking-link.ts b/packages/medusa/src/models/tracking-link.ts index d390be5e9c..eb7669d1c3 100644 --- a/packages/medusa/src/models/tracking-link.ts +++ b/packages/medusa/src/models/tracking-link.ts @@ -26,6 +26,9 @@ export class TrackingLink extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "tlink") diff --git a/packages/medusa/src/models/user.ts b/packages/medusa/src/models/user.ts index a7159e10c3..f78508d2c0 100644 --- a/packages/medusa/src/models/user.ts +++ b/packages/medusa/src/models/user.ts @@ -4,9 +4,23 @@ import { DbAwareColumn } from "../utils/db-aware-column" import { SoftDeletableEntity } from "../interfaces/models/soft-deletable-entity" import { generateEntityId } from "../utils/generate-entity-id" +/** + * @enum + * + * The user's role. These roles don't change the user's capabilities or provide access-control features. + */ export enum UserRoles { + /** + * The user is an admin. + */ ADMIN = "admin", + /** + * The user is a team member. + */ MEMBER = "member", + /** + * The user is a developer. + */ DEVELOPER = "developer", } @@ -30,6 +44,9 @@ export class User extends SoftDeletableEntity { @Column({ nullable: true }) last_name: string + /** + * @apiIgnore + */ @Column({ nullable: true, select: false }) password_hash: string @@ -39,6 +56,9 @@ export class User extends SoftDeletableEntity { @DbAwareColumn({ type: "jsonb", nullable: true }) metadata: Record + /** + * @apiIgnore + */ @BeforeInsert() private beforeInsert(): void { this.id = generateEntityId(this.id, "usr") diff --git a/packages/medusa/src/types/common.ts b/packages/medusa/src/types/common.ts index 44972e3c6c..ba002da6a0 100644 --- a/packages/medusa/src/types/common.ts +++ b/packages/medusa/src/types/common.ts @@ -110,92 +110,189 @@ export type QueryConfig = { isList?: boolean } +/** + * @interface + * + * Request parameters used to configure and paginate retrieved data. + */ export type RequestQueryFields = { + /** + * {@inheritDoc FindParams.expand} + */ expand?: string + /** + * {@inheritDoc FindParams.fields} + */ fields?: string + /** + * {@inheritDoc FindPaginationParams.offset} + */ offset?: number + /** + * {@inheritDoc FindPaginationParams.limit} + */ limit?: number + /** + * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`. + */ order?: string } +/** + * @interface + * + * Pagination fields returned in the response of an API route. + * + * @prop limit - The maximum number of items that can be returned in the list. + * @prop offset - The number of items skipped before the returned items in the list. + * @prop count - The total number of items available. + */ export type PaginatedResponse = { limit: number; offset: number; count: number } +/** + * @interface + * + * The response returned for a DELETE request. + */ export type DeleteResponse = { + /** + * The ID of the deleted item. + */ id: string + /** + * The type of the deleted item. + */ object: string + /** + * Whether the item was deleted successfully. + */ deleted: boolean } export class EmptyQueryParams {} +/** + * Fields used to apply flexible filters on dates. + */ export class DateComparisonOperator { + /** + * The filtered date must be less than this value. + */ @IsOptional() @IsDate() @Transform(transformDate) lt?: Date + /** + * The filtered date must be greater than this value. + */ @IsOptional() @IsDate() @Transform(transformDate) gt?: Date + /** + * The filtered date must be greater than or equal to this value. + */ @IsOptional() @IsDate() @Transform(transformDate) gte?: Date + /** + * The filtered date must be less than or equal to this value. + */ @IsOptional() @IsDate() @Transform(transformDate) lte?: Date } +/** + * Fields used to apply flexible filters on strings. + */ export class StringComparisonOperator { + /** + * The filtered string must be less than this value. + */ @IsString() @IsOptional() lt?: string + /** + * The filtered string must be greater than this value. + */ @IsString() @IsOptional() gt?: string + /** + * The filtered string must be greater than or equal to this value. + */ @IsString() @IsOptional() gte?: string + /** + * The filtered string must be less than or equal to this value. + */ @IsString() @IsOptional() lte?: string + /** + * The filtered string must contain this value. + */ @IsString() @IsOptional() contains?: string + /** + * The filtered string must start with this value. + */ @IsString() @IsOptional() starts_with?: string + /** + * The filtered string must end with this value. + */ @IsString() @IsOptional() ends_with?: string } +/** + * Fields used to apply flexible filters on numbers. + */ export class NumericalComparisonOperator { + /** + * The filtered number must be less than this value. + */ @IsNumber() @IsOptional() @Type(() => Number) lt?: number + /** + * The filtered number must be greater than this value. + */ @IsNumber() @IsOptional() @Type(() => Number) gt?: number + /** + * The filtered number must be greater than or equal to this value. + */ @IsNumber() @IsOptional() @Type(() => Number) gte?: number + /** + * The filtered number must be less than or equal to this value. + */ @IsNumber() @IsOptional() @Type(() => Number) @@ -221,6 +318,7 @@ export class NumericalComparisonOperator { * example: 16128234334802 * company: * type: string + * description: Company * address_1: * description: Address line 1 * type: string @@ -396,22 +494,42 @@ export class AddressCreatePayload { postal_code: string } +/** + * Parameters that can be used to configure how data is retrieved. + */ export class FindParams { + /** + * Comma-separated relations that should be expanded in the returned data. + */ @IsString() @IsOptional() expand?: string + /** + * Comma-separated fields that should be included in the returned data. + */ @IsString() @IsOptional() fields?: string } +/** + * Parameters that can be used to configure how a list of data is paginated. + */ export class FindPaginationParams { + /** + * The number of items to skip when retrieving a list. + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset?: number = 0 + /** + * Limit the number of items returned in the list. + * @defaultValue 20 + */ @IsNumber() @IsOptional() @Type(() => Number) @@ -425,12 +543,23 @@ export function extendedFindParamsMixin({ limit?: number offset?: number } = {}): ClassConstructor { + /** + * {@inheritDoc FindParams} + */ class FindExtendedPaginationParams extends FindParams { + /** + * {@inheritDoc FindPaginationParams.offset} + * @defaultValue 0 + */ @IsNumber() @IsOptional() @Type(() => Number) offset?: number = offset ?? 0 + /** + * {@inheritDoc FindPaginationParams.limit} + * @defaultValue 20 + */ @IsNumber() @IsOptional() @Type(() => Number) diff --git a/packages/medusa/src/types/customer-groups.ts b/packages/medusa/src/types/customer-groups.ts index 10accad6d3..84db005770 100644 --- a/packages/medusa/src/types/customer-groups.ts +++ b/packages/medusa/src/types/customer-groups.ts @@ -4,31 +4,52 @@ import { IsType } from "../utils/validators/is-type" import { DateComparisonOperator, StringComparisonOperator } from "./common" +/** + * Filters to apply on the retrieved customer groups. + */ export class FilterableCustomerGroupProps { + /** + * IDs to filter customer groups by. + */ @IsOptional() @ValidateNested() @IsType([String, [String], StringComparisonOperator]) id?: string | string[] | StringComparisonOperator + /** + * Search term to search customer groups by their name. + */ @IsString() @IsOptional() q?: string + /** + * Names to filter customer groups by. + */ @IsOptional() @IsArray() @IsString({ each: true }) name?: string[] + /** + * Date filters to apply on the customer groups' `update_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the customer groups' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Filter customer groups by their associated discount condition's ID. + */ @IsString() @IsOptional() discount_condition_id?: string diff --git a/packages/medusa/src/types/customers.ts b/packages/medusa/src/types/customers.ts index 9711e772ac..51b5e16cb1 100644 --- a/packages/medusa/src/types/customers.ts +++ b/packages/medusa/src/types/customers.ts @@ -3,16 +3,28 @@ import { IsBoolean, IsOptional, IsString } from "class-validator" import { optionalBooleanMapper } from "../utils/validators/is-boolean" import { AddressPayload } from "./common" +/** + * Filters used to filter retrieved customers. + */ export class AdminListCustomerSelector { + /** + * Search term used to search customers' email, first name, last name. + */ @IsString() @IsOptional() q?: string + /** + * Filter customers by whether they have an account. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value)) has_account?: boolean + /** + * Filter customers by the customer's customer groups. + */ @IsOptional() @IsString({ each: true }) groups?: string[] diff --git a/packages/medusa/src/types/discount.ts b/packages/medusa/src/types/discount.ts index 24374975c0..a22f1bd89c 100644 --- a/packages/medusa/src/types/discount.ts +++ b/packages/medusa/src/types/discount.ts @@ -48,17 +48,32 @@ export class FilterableDiscountProps { rule?: AdminGetDiscountsDiscountRuleParams } +/** + * Filters to apply on discounts' rules. + */ export class AdminGetDiscountsDiscountRuleParams { + /** + * Type to filter discount rules by. + */ @IsOptional() @IsEnum(DiscountRuleType) type?: DiscountRuleType + /** + * Allocation to filter discount rules by. + */ @IsOptional() @IsEnum(AllocationType) allocation?: AllocationType } +/** + * Fields to create or update a discount condition. + */ export class AdminUpsertConditionsReq { + /** + * The products associated with the discount condition, if the discount condition's type is `products`. + */ @Validate(ExactlyOne, [ "product_collections", "product_types", @@ -70,6 +85,9 @@ export class AdminUpsertConditionsReq { @IsString({ each: true }) products?: string[] + /** + * The product collections associated with the discount condition, if the discount condition's type is `product_collections`. + */ @Validate(ExactlyOne, [ "products", "product_types", @@ -81,6 +99,9 @@ export class AdminUpsertConditionsReq { @IsString({ each: true }) product_collections?: string[] + /** + * The product types associated with the discount condition, if the discount condition's type is `product_types`. + */ @Validate(ExactlyOne, [ "product_collections", "products", @@ -92,6 +113,9 @@ export class AdminUpsertConditionsReq { @IsString({ each: true }) product_types?: string[] + /** + * The product tags associated with the discount condition, if the discount condition's type is `product_tags`. + */ @Validate(ExactlyOne, [ "product_collections", "product_types", @@ -103,6 +127,9 @@ export class AdminUpsertConditionsReq { @IsString({ each: true }) product_tags?: string[] + /** + * The customer groups associated with the discount condition, if the discount condition's type is `customer_groups`. + */ @Validate(ExactlyOne, [ "product_collections", "product_types", diff --git a/packages/medusa/src/types/orders.ts b/packages/medusa/src/types/orders.ts index c3d99240c4..7e6f278504 100644 --- a/packages/medusa/src/types/orders.ts +++ b/packages/medusa/src/types/orders.ts @@ -22,33 +22,111 @@ export type TotalsContext = { includes?: { returnable_items?: boolean } } +/** + * @enum + * + * The status of an order. + */ enum OrderStatus { + /** + * Order is pending. + */ pending = "pending", + /** + * Order is completed. An order is completed when it's paid and fulfilled. + */ completed = "completed", + /** + * Order is archived. + */ archived = "archived", + /** + * Order is canceled. + */ canceled = "canceled", + /** + * Order requires an action. This status is applied when the order's payment or fulfillment requires an additional action. + */ requires_action = "requires_action", } +/** + * @enum + * + * The fulfillment status of an order. + */ enum FulfillmentStatus { + /** + * The order isn't fulfilled. + */ not_fulfilled = "not_fulfilled", + /** + * All of the order's items are fulfilled. + */ fulfilled = "fulfilled", + /** + * Some, but not all, of the order's items are fulfilled. + */ partially_fulfilled = "partially_fulfilled", + /** + * All of the order's items are shipped. + */ shipped = "shipped", + /** + * Some, but not all, of the order's items are shipped. + */ partially_shipped = "partially_shipped", + /** + * The order's fulfillments are canceled. + */ canceled = "canceled", + /** + * All of the order's items are returned. + */ returned = "returned", + /** + * Some, but not all, of the order's items are returned. + */ partially_returned = "partially_returned", + /** + * The order's fulfillment requires an action. + */ requires_action = "requires_action", } +/** + * @enum + * + * The payment status of the order. + */ enum PaymentStatus { + /** + * The order's payment is captured. + */ captured = "captured", + /** + * The order's payment is awaiting. + */ awaiting = "awaiting", + /** + * The order's payment isn't paid. + */ not_paid = "not_paid", + /** + * The order's payment is fully refunded. + */ refunded = "refunded", + /** + * The order's payment is partially refunded. + */ partially_refunded = "partially_refunded", + /** + * The order's payment is canceled. + */ canceled = "canceled", + /** + * The order's payment requires an action. + */ requires_action = "requires_action", } @@ -179,72 +257,123 @@ export const defaultAdminOrdersFields = [ "no_notification", ] as (keyof Order)[] +/** + * Filters to apply on the retrieved orders. + */ export class AdminListOrdersSelector { + /** + * Search term to search orders' shipping address, first name, email, and display ID. + */ @IsString() @IsOptional() q?: string + /** + * ID to filter orders by. + */ @IsString() @IsOptional() id?: string + /** + * Statuses to filter orders by. + */ @IsArray() @IsEnum(OrderStatus, { each: true }) @IsOptional() status?: string[] + /** + * Fulfillment statuses to filter orders by. + */ @IsArray() @IsEnum(FulfillmentStatus, { each: true }) @IsOptional() fulfillment_status?: string[] + /** + * Payment statuses to filter orders by. + */ @IsArray() @IsEnum(PaymentStatus, { each: true }) @IsOptional() payment_status?: string[] + /** + * Display ID to filter orders by. + */ @IsString() @IsOptional() display_id?: string + /** + * Cart ID to filter orders by. + */ @IsString() @IsOptional() cart_id?: string + /** + * Customer ID to filter orders by. + */ @IsString() @IsOptional() customer_id?: string + /** + * Email to filter orders by. + */ @IsString() @IsOptional() email?: string + /** + * Regions to filter orders by. + */ @IsOptional() @IsType([String, [String]]) region_id?: string | string[] + /** + * Currency code to filter orders by. + */ @IsString() @IsOptional() currency_code?: string + /** + * Tax rate to filter orders by. + */ @IsString() @IsOptional() tax_rate?: string + /** + * Sales channel IDs to filter orders by. + */ @IsArray() @IsOptional() sales_channel_id?: string[] + /** + * Date filters to apply on the orders' `canceled_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) canceled_at?: DateComparisonOperator + /** + * Date filters to apply on the orders' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the orders' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/types/price-list.ts b/packages/medusa/src/types/price-list.ts index dc1d8babc5..24ea5e1225 100644 --- a/packages/medusa/src/types/price-list.ts +++ b/packages/medusa/src/types/price-list.ts @@ -12,55 +12,110 @@ import { PriceList } from "../models/price-list" import { DateComparisonOperator, FindConfig } from "./common" import { XorConstraint } from "./validators/xor" +/** + * @enum + * + * The type of price list. + */ export enum PriceListType { + /** + * The price list is used for a sale. + */ SALE = "sale", + /** + * The price list is used to override original prices for specific conditions. + */ OVERRIDE = "override", } +/** + * @enum + * + * The status of a price list. + */ export enum PriceListStatus { + /** + * The price list is active, meaning its prices are applied to customers. + */ ACTIVE = "active", + /** + * The price list is a draft, meaning its not yet applied to customers. + */ DRAFT = "draft", } +/** + * Filters to apply on the retrieved price lists. + */ export class FilterablePriceListProps { + /** + * IDs to filter price lists by. + */ @IsString() @IsOptional() id?: string + /** + * Search terms to search price lists' description, name, and customer group's name. + */ @IsString() @IsOptional() q?: string + /** + * Statuses to filter price lists by. + */ @IsOptional() @IsEnum(PriceListStatus, { each: true }) status?: PriceListStatus[] + /** + * Name to filter price lists by. + */ @IsString() @IsOptional() name?: string + /** + * Filter price lists by their associated customer groups. + */ @IsOptional() @IsString({ each: true }) customer_groups?: string[] + /** + * Description to filter price lists by. + */ @IsString() @IsOptional() description?: string + /** + * Types to filter price lists by. + */ @IsOptional() @IsEnum(PriceListType, { each: true }) type?: PriceListType[] + /** + * Date filters to apply on the price lists' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the price lists' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the price lists' `deleted_at` date. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) diff --git a/packages/medusa/src/types/price-selection.ts b/packages/medusa/src/types/price-selection.ts index 16f0333d86..a011e886fc 100644 --- a/packages/medusa/src/types/price-selection.ts +++ b/packages/medusa/src/types/price-selection.ts @@ -2,21 +2,39 @@ import { IsOptional, IsString } from "class-validator" import { FindParams } from "./common" +/** + * The context to apply on retrieved prices. + */ export class PriceSelectionParams extends FindParams { + /** + * Retrieve prices for a cart ID. + */ @IsOptional() @IsString() cart_id?: string + /** + * Retrieve prices for a region ID. + */ @IsOptional() @IsString() region_id?: string + /** + * Retrieve prices for a currency code. + */ @IsOptional() @IsString() currency_code?: string } +/** + * The context to apply on retrieved prices by a user admin. + */ export class AdminPriceSelectionParams extends PriceSelectionParams { + /** + * Retrieve prices for a customer ID. + */ @IsOptional() @IsString() customer_id?: string diff --git a/packages/medusa/src/types/pricing.ts b/packages/medusa/src/types/pricing.ts index e4d13941cd..0acb27286d 100644 --- a/packages/medusa/src/types/pricing.ts +++ b/packages/medusa/src/types/pricing.ts @@ -3,20 +3,63 @@ import { MoneyAmount, Product, ProductVariant, ShippingOption } from "../models" import { PriceSelectionContext } from "../interfaces/price-selection-strategy" import { TaxServiceRate } from "./tax-service" +/** + * Pricing fields for product variants. + */ export type ProductVariantPricing = { + /** + * The list of prices. + */ prices: MoneyAmount[] + /** + * The original price of the variant. + */ original_price: number | null + /** + * The lowest price among the retrieved prices. + */ calculated_price: number | null + /** + * Whether the `original_price` field includes taxes. + * + * @featureFlag tax_inclusive_pricing + */ original_price_includes_tax?: boolean | null + /** + * Whether the `calculated_price` field includes taxes. + * + * @featureFlag tax_inclusive_pricing + */ calculated_price_includes_tax?: boolean | null + /** + * Either `default` if the `calculated_price` is the original price, or the type of the price list applied, if any. + */ calculated_price_type?: string | null } & TaxedPricing +/** + * Pricing fields related to taxes. + */ export type TaxedPricing = { + /** + * The price after applying the tax amount on the original price. + */ original_price_incl_tax: number | null + /** + * The price after applying the tax amount on the calculated price. + */ calculated_price_incl_tax: number | null + /** + * The tax amount applied to the original price. + */ original_tax: number | null + /** + * The tax amount applied to the calculated price. + */ calculated_tax: number | null + /** + * The list of tax rates. + */ tax_rates: TaxServiceRate[] | null } @@ -117,6 +160,7 @@ export type PricedVariant = Partial & ProductVariantPricing * - type: object * properties: * variants: + * description: "The product variants and their prices." * type: array * items: * $ref: "#/components/schemas/PricedVariant" diff --git a/packages/medusa/src/types/product.ts b/packages/medusa/src/types/product.ts index 59d51fabdb..571cd0a881 100644 --- a/packages/medusa/src/types/product.ts +++ b/packages/medusa/src/types/product.ts @@ -25,80 +25,136 @@ import SalesChannelFeatureFlag from "../loaders/feature-flags/sales-channels" import { optionalBooleanMapper } from "../utils/validators/is-boolean" /** - * API Level DTOs + Validation rules + * Filters to apply on retrieved products. */ export class FilterableProductProps { + /** + * IDs to filter products by. + */ @IsOptional() @IsType([String, [String]]) id?: string | string[] + /** + * Search term to search products' title, description, variants' title and sku, and collections' title. + */ @IsString() @IsOptional() q?: string + /** + * Statuses to filter products by. + */ @IsOptional() @IsEnum(ProductStatus, { each: true }) status?: ProductStatus[] + /** + * Filter products by their associated price lists' ID. + */ @IsArray() @IsOptional() price_list_id?: string[] + /** + * Filter products by their associated product collection's ID. + */ @IsArray() @IsOptional() collection_id?: string[] + /** + * Filter products by their associated tags' value. + */ @IsArray() @IsOptional() tags?: string[] + /** + * Title to filter products by. + */ @IsString() @IsOptional() title?: string + /** + * Description to filter products by. + */ @IsString() @IsOptional() description?: string + /** + * Handle to filter products by. + */ @IsString() @IsOptional() handle?: string + /** + * Filter products by whether they're gift cards. + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value.toLowerCase())) is_giftcard?: boolean + /** + * Filter products by their associated product type's ID. + */ @IsArray() @IsOptional() type_id?: string[] + /** + * Filter products by their associated sales channels' ID. + */ @FeatureFlagDecorators(SalesChannelFeatureFlag.key, [IsOptional(), IsArray()]) sales_channel_id?: string[] + /** + * Filter products by their associated discount condition's ID. + */ @IsString() @IsOptional() discount_condition_id?: string + /** + * Filter products by their associated product category's ID. + */ @IsArray() @IsOptional() category_id?: string[] + /** + * Whether to include product category children in the response. + * + * @featureFlag product_categories + */ @IsBoolean() @IsOptional() @Transform(({ value }) => optionalBooleanMapper.get(value.toLowerCase())) include_category_children?: boolean + /** + * Date filters to apply on the products' `created_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) created_at?: DateComparisonOperator + /** + * Date filters to apply on the products' `updated_at` date. + */ @IsOptional() @ValidateNested() @Type(() => DateComparisonOperator) updated_at?: DateComparisonOperator + /** + * Date filters to apply on the products' `deleted_at` date. + */ @ValidateNested() @IsOptional() @Type(() => DateComparisonOperator) @@ -257,11 +313,20 @@ export class ProductTagReq { value: string } +/** + * The details of a product type, used to create or update an existing product type. + */ export class ProductTypeReq { + /** + * The ID of the product type. It's only required when referring to an existing product type. + */ @IsString() @IsOptional() id?: string + /** + * The value of the product type. + */ @IsString() value: string } diff --git a/packages/medusa/src/types/store.ts b/packages/medusa/src/types/store.ts index 3c60805f0e..cb64d2dceb 100644 --- a/packages/medusa/src/types/store.ts +++ b/packages/medusa/src/types/store.ts @@ -43,12 +43,16 @@ export type ModulesResponse = sdkModulesResponse * - modules * properties: * payment_providers: + * description: "The store's payment providers." * $ref: "#/components/schemas/PaymentProvider" * fulfillment_providers: + * description: "The store's fulfillment providers." * $ref: "#/components/schemas/FulfillmentProvider" * feature_flags: + * description: "The feature flags enabled in the store's backend." * $ref: "#/components/schemas/FeatureFlagsResponse" * modules: + * description: "The modules installed in the store's backend." * $ref: "#/components/schemas/ModulesResponse" * */ diff --git a/packages/medusa/src/types/tax-service.ts b/packages/medusa/src/types/tax-service.ts index 1c70fe756a..66e91d04c6 100644 --- a/packages/medusa/src/types/tax-service.ts +++ b/packages/medusa/src/types/tax-service.ts @@ -13,8 +13,17 @@ export type TaxLinesMaps = { * plugin. */ export type TaxServiceRate = { + /** + * The tax rate. + */ rate?: number | null + /** + * The tax rate's name. + */ name: string + /** + * The tax rate's code. + */ code: string | null } diff --git a/packages/types/src/common/common.ts b/packages/types/src/common/common.ts index 094b4ebe2e..b7f11f375a 100644 --- a/packages/types/src/common/common.ts +++ b/packages/types/src/common/common.ts @@ -136,9 +136,21 @@ export type PaginatedResponse = { count: number } +/** + * The fields returned in the response of a DELETE request. + */ export type DeleteResponse = { + /** + * The ID of the item that was deleted. + */ id: string + /** + * The type of the item that was deleted. + */ object: string + /** + * Whether the item was deleted successfully. + */ deleted: boolean } diff --git a/packages/types/src/inventory/common.ts b/packages/types/src/inventory/common.ts index 640f38d458..af8f54b588 100644 --- a/packages/types/src/inventory/common.ts +++ b/packages/types/src/inventory/common.ts @@ -9,6 +9,10 @@ import { * required: * - sku * properties: + * id: + * description: The inventory item's ID. + * type: string + * example: "iitem_12334" * sku: * description: The Stock Keeping Unit (SKU) code of the Inventory Item. * type: string diff --git a/packages/types/src/stock-location/common.ts b/packages/types/src/stock-location/common.ts index b491dff151..67e41e227c 100644 --- a/packages/types/src/stock-location/common.ts +++ b/packages/types/src/stock-location/common.ts @@ -144,6 +144,7 @@ export type StockLocationDTO = { * - type: object * properties: * sales_channels: + * description: "The associated sales channels." * $ref: "#/components/schemas/SalesChannel" */ export type StockLocationExpandedDTO = StockLocationDTO & { diff --git a/www/apps/api-reference/app/_mdx/admin.mdx b/www/apps/api-reference/app/_mdx/admin.mdx index 489623461f..3afdee9c71 100644 --- a/www/apps/api-reference/app/_mdx/admin.mdx +++ b/www/apps/api-reference/app/_mdx/admin.mdx @@ -1096,17 +1096,12 @@ export default Products`, In the response of listing API Routes, aside from the entities retrieved, -there are three pagination-related fields returned: `count`, `limit`, and -`offset`. +there are three pagination-related fields returned: -Similar to the query parameters, `limit` is the maximum number of items that -can be returned in the response, and `field` is the number of items that -were skipped before the entities in the result. - - -`count` is the total number of available items of this entity. It can be -used to determine how many pages are there. +- `limit`: the maximum number of items that can be returned in the response. +- `offset`: the number of items that were skipped before the entities in the result. +- `count`: the total number of available items of this entity. It can be used to determine how many pages are there. For example, if the `count` is 100 and the `limit` is 50, you can divide the diff --git a/www/apps/api-reference/app/_mdx/store.mdx b/www/apps/api-reference/app/_mdx/store.mdx index 0a04a043b7..567d9b9f91 100644 --- a/www/apps/api-reference/app/_mdx/store.mdx +++ b/www/apps/api-reference/app/_mdx/store.mdx @@ -155,7 +155,7 @@ You can learn more about publishable API keys and how to use them in [this docum ### How to Create a Publishable API Key You can create a publishable API key either using the [admin REST APIs](https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys), -or using the [Medusa admin](https://docs.medusajs.com/user-guide/settings/publishable-api-keys). +or using the [Medusa admin dashboard](https://docs.medusajs.com/user-guide/settings/publishable-api-keys). ### How to Use a Publishable API Key @@ -1038,17 +1038,12 @@ export default Products`, In the response of listing API Routes, aside from the entities retrieved, -there are three pagination-related fields returned: `count`, `limit`, and -`offset`. +there are three pagination-related fields returned: -Similar to the query parameters, `limit` is the maximum number of items that -can be returned in the response, and `field` is the number of items that -were skipped before the entities in the result. - - -`count` is the total number of available items of this entity. It can be -used to determine how many pages are there. +- `limit`: the maximum number of items that can be returned in the response. +- `offset`: the number of items that were skipped before the entities in the result. +- `count`: the total number of available items of this entity. It can be used to determine how many pages are there. For example, if the `count` is 100 and the `limit` is 50, you can divide the diff --git a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx index 49489cb056..c70a1d18e2 100644 --- a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx +++ b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx @@ -7,9 +7,8 @@ import type { TagsOperationDescriptionSectionResponsesProps } from "./Responses" import dynamic from "next/dynamic" import TagsOperationDescriptionSectionParameters from "./Parameters" import MDXContentClient from "@/components/MDXContent/Client" -import type { TagsOperationFeatureFlagNoticeProps } from "../FeatureFlagNotice" import { useArea } from "../../../../providers/area" -import { Feedback, Badge, NextLink } from "docs-ui" +import { Feedback, Badge, NextLink, FeatureFlagNotice } from "docs-ui" import { usePathname } from "next/navigation" import formatReportLink from "../../../../utils/format-report-link" @@ -27,12 +26,6 @@ const TagsOperationDescriptionSectionResponses = dynamic( async () => import("./Responses") ) as React.FC - -const TagsOperationFeatureFlagNotice = - dynamic( - async () => import("../FeatureFlagNotice") - ) as React.FC - type TagsOperationDescriptionSectionProps = { operation: Operation } @@ -52,7 +45,7 @@ const TagsOperationDescriptionSection = ({ )} {operation["x-featureFlag"] && ( - ( async () => (await import("docs-ui")).Tooltip ) as React.FC -const TagsOperationFeatureFlagNotice = - dynamic( - async () => import("../../FeatureFlagNotice") - ) as React.FC - export type TagOperationParametersNameProps = { name: string isRequired?: boolean @@ -35,25 +29,13 @@ const TagOperationParametersName = ({ {schema["x-expandable"] && ( <>
- - If this request accepts an expand parameter, -
this field can be{" "} - expanded into an - object. - - } - clickable - > - expandable - + )} {schema["x-featureFlag"] && ( <>
- diff --git a/www/apps/docs/content/development/batch-jobs/create.mdx b/www/apps/docs/content/development/batch-jobs/create.mdx index 1be810de90..20574693b1 100644 --- a/www/apps/docs/content/development/batch-jobs/create.mdx +++ b/www/apps/docs/content/development/batch-jobs/create.mdx @@ -284,7 +284,7 @@ npx medusa develop You must also use an authenticated user to send batch job requests. You can refer to the [authentication guide in the API reference](https://docs.medusajs.com/api/admin#authentication) for more details. -If you follow along with the JS Client code snippets, make sure to [install and set it up first](../../js-client/overview.md). +If you follow along with the JS Client code snippets, make sure to [install and set it up first](../../js-client/overview.mdx). ### Create Batch Job diff --git a/www/apps/docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx b/www/apps/docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx index 8b84b058d2..cf9b9e59d7 100644 --- a/www/apps/docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx +++ b/www/apps/docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx @@ -43,7 +43,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/development/publishable-api-keys/storefront/use-in-requests.md b/www/apps/docs/content/development/publishable-api-keys/storefront/use-in-requests.md index 7c3fbcf0bd..fc8ed71171 100644 --- a/www/apps/docs/content/development/publishable-api-keys/storefront/use-in-requests.md +++ b/www/apps/docs/content/development/publishable-api-keys/storefront/use-in-requests.md @@ -20,7 +20,7 @@ If you don't pass a publishable API Key for the store API Routes `/store/product ## Using Medusa JS Client -When using [Medusa’s JS Client](../../../js-client/overview.md), you can pass it to the client only once when you create the instance of the client: +When using [Medusa’s JS Client](../../../js-client/overview.mdx), you can pass it to the client only once when you create the instance of the client: ```ts const medusa = new Medusa({ diff --git a/www/apps/docs/content/js-client/overview.md b/www/apps/docs/content/js-client/overview.md deleted file mode 100644 index a0a4356c8e..0000000000 --- a/www/apps/docs/content/js-client/overview.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -description: 'Learn how to install the Medusa JS Client in a storefront. Medusa JS Client provides easy access to the Medusa API from a client written in TypeScript.' ---- - -# Medusa JS Client - -The [Medusa JS Client](https://www.npmjs.com/package/@medusajs/medusa-js) provides easy access to the Medusa API from a client written in TypeScript. This reference guides you to learn what methods the client has and how you can use them. - -This client can be use as an alternative to directly interacting with the [REST APIs](https://docs.medusajs.com/api/store). - -## Installation - -To install the Medusa JS Client run the following command: - -```bash npm2yarn -npm install @medusajs/medusa-js -``` - ---- - -## Usage - -Import Medusa as a default import and initiate it: - -```ts -import Medusa from "@medusajs/medusa-js" - -const medusa = new Medusa() -``` - -### Troubleshooting: Could not find a declaration file for module '@medusajs/medusa-js' - -If you import `@medusajs/medusa-js` in your code and see the following TypeScript error: - -```bash -Could not find a declaration file for module '@medusajs/medusa-js' -``` - -Make sure to set `moduleResolution` in your `tsconfig.json` to `nodenext` or `node`: - -```json title=tsconfig.json -{ - "compilerOptions": { - "moduleResolution": "nodenext", - // ... - }, - // ... -} -``` - ---- - -## How to Use this Reference - -You'll find in the sidebar of this reference names of different resources. These resources are properties in the Medusa instance you initialize and you can access them directly using the instance. Then, you'll be able to access the methods or nested resources within those resources. - -For example, to create a new customer you can access the [create](../references/js-client/customers/classes/customers.CustomerResource.mdx#create) method under the [customers](../references/js-client/customers/classes/customers.CustomerResource.mdx) property of your client: - -```ts -import Medusa from "@medusajs/medusa-js" - -const medusa = new Medusa() - -// use method -medusa.customers.create({ - // data -}) -``` - -The `customers` resource also has another resource `addresses` nested inside it with its own method that you can access similarly: - -```ts -medusa.customers.addresses.addAddress({ - // data -}) -``` - ---- - -## Authentication - -Authentication can be achieved in two ways using the `medusa-js` client: either by utilizing API keys or by using cookie based authentication. Each method has its own unique use case. - -### Using API keys - -API keys can only be used for admin functionality in Medusa since only users of the admin system have API keys. Refer to the [Configuration](#configuration) section to learn how to add the API key to requests. - -You can follow [this guide](https://docs.medusajs.com/api/admin#authentication) to learn how to create an API key for an admin user. - -### Using cookies - -Authentication using cookies is done automatically by Axios, which is used within the Medusa JS Client, when authenticating using the [auth](../references/js-client/auth/classes/auth.AuthResource.mdx) API Routes. After authentication, all subsequent calls will be authenticated. - ---- - -## Configuration - -### Initialize with config object - -The package can be initialized with several options: - -```ts -const medusa = new Medusa({ - maxRetries: 3, - baseUrl: "https://api.example.com", -}) -``` - -| Option | Default | Description | -| ------------------- | ------------------------- | --------------------------------------------------------- | -| `maxRetries` | `0` | The amount of times a request is retried. | -| `baseUrl` | `'http://localhost:9000'` | The url to which requests are made to. | -| `apiKey` | `''` | Optional API key used for authenticating admin requests. | -| `publishableApiKey` | `''` | Optional publishable API key used for storefront requests. You can create a publishable API key either using the [admin APIs](../development/publishable-api-keys/admin/manage-publishable-api-keys.mdx) or the [Medusa admin](../user-guide/settings/publishable-api-keys.mdx). | diff --git a/www/apps/docs/content/js-client/overview.mdx b/www/apps/docs/content/js-client/overview.mdx new file mode 100644 index 0000000000..32f61f9d8a --- /dev/null +++ b/www/apps/docs/content/js-client/overview.mdx @@ -0,0 +1,576 @@ +--- +description: 'Learn how to install the Medusa JS Client in a storefront. Medusa JS Client provides easy access to the Medusa API from a client written in TypeScript.' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Medusa JS Client + +The [Medusa JS Client](https://www.npmjs.com/package/@medusajs/medusa-js) provides easy access to the Medusa backend's REST APIs within TypeScript or JavaScript frontend projects. + +For example, if you're creating a storefront with frameworks like Nuxt, you can send requests to the backend using this client. + +This reference provides details on the available methods including examples of each. + +## Installation + +To install the Medusa JS Client run the following command: + +```bash npm2yarn +npm install @medusajs/medusa-js +``` + +--- + +## Usage + +To use the Medusa client, import `Medusa` and initialize the client: + +```ts +import Medusa from "@medusajs/medusa-js" + +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, +}) +``` + +Where `MEDUSA_BACKEND_URL` is the URL to your Medusa backend. If the `baseUrl` option is not provided, the default backend URL used is `http://localhost:9000`. + +After initialization, you can use the client's properties and methods to send requests to the Medusa backend. + +
+ +Troubleshooting: Could not find a declaration file for module '@medusajs/medusa-js' + + +If you import `@medusajs/medusa-js` in your code and see the following TypeScript error: + +```bash +Could not find a declaration file for module '@medusajs/medusa-js' +``` + +Make sure to set `moduleResolution` in your `tsconfig.json` to `nodenext` or `node`: + +```json title=tsconfig.json +{ + "compilerOptions": { + "moduleResolution": "nodenext", + // ... + }, + // ... +} +``` + +
+ +## How to Use this Reference + +You'll find in the sidebar of this reference names of different resources. These resources are properties in the Medusa client instance you initialize. You can access the methods or nested resources of each of the properties to send requests to the backend. + +For example, to create a new customer you can access the [create](../references/js-client/customers/classes/customers.CustomerResource.mdx#create) method under the [customers](../references/js-client/customers/classes/customers.CustomerResource.mdx) property of your client: + +```ts +import Medusa from "@medusajs/medusa-js" + +const medusa = new Medusa() + +// use method +medusa.customers.create({ + // data +}) +``` + +The `customers` resource also has another resource `addresses` nested inside it with its own method that you can access similarly: + +```ts +medusa.customers.addresses.addAddress({ + // data +}) +``` + +--- + +## Client Options + +The client accepts the following options on initialization: + +| Option | Default | Description | +| ------------------- | ------------------------- | --------------------------------------------------------- | +| `maxRetries` | `0` | The amount of times a request is retried. | +| `baseUrl` | `'http://localhost:9000'` | The url to which requests are made to. | +| `apiKey` | `''` | Optional API key used for authenticating admin requests. | +| `publishableApiKey` | `''` | Optional publishable API key used for storefront requests. You can create a publishable API key either using the [admin APIs](../development/publishable-api-keys/admin/manage-publishable-api-keys.mdx) or the [Medusa admin](../user-guide/settings/publishable-api-keys.mdx). | +| `customHeaders` | `{}` | Optional headers to attach to every request. | + + +For example: + +```ts +const medusa = new Medusa({ + maxRetries: 3, + baseUrl: "https://api.example.com", +}) +``` + +--- + +## Authentication + +### JWT Token + +You can use a JWT token to authenticate both admin users and customers. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications. + +You can authenticate the admin user using the [admin.auth.getToken](../references/js-client/admin_auth/classes/admin_auth.AdminAuthResource.mdx#getToken) method, and the customer using the [auth.getToken](../references/js-client/auth/classes/auth.AuthResource.mdx#getToken) method. + +Once the user or customer is authenticated successfully, the Medusa client automatically attaches an Authorization Bearer header to all subsequent requests. + +For example: + + + + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +await medusa.admin.auth.getToken({ + email: "user@example.com", + password: "supersecret", +}) +// send authenticated requests now +``` + + + + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +await medusa.auth.getToken({ + email: "user@example.com", + password: "supersecret", +}) +// send authenticated requests now +``` + + + + +### Cookie Session ID + +You can authenticate admin users or customers using cookie session ID. + +You can authenticate the admin user using the [admin.auth.createSession](../references/js-client/admin_auth/classes/admin_auth.AdminAuthResource.mdx#createSession) method, and the customer using the [auth.authenticate](../references/js-client/auth/classes/auth.AuthResource.mdx#authenticate) method. + +Once the user or customer is authenticated successfully, the Medusa client sets and attached the session ID in the cookie for all subsequent requests. + +For example: + + + + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +await medusa.admin.AdminAuthResource.createSession({ + email: "user@example.com", + password: "supersecret", +}) +// send authenticated requests now +``` + + + + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +await medusa.auth.authenticate({ + email: "user@example.com", + password: "user@example.com", +}) +// send authenticated requests now +``` + + + + +### API Key + +You can authenticate admin users with a personal API Token. + +If a user doesn't have a personal API token, create one with the [admin.users.update](../references/js-client/admin_users/classes/admin_users.AdminUsersResource.mdx#update) method: + + + + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.users.update(userId, { + api_token, +}) +.then(({ user }) => { + console.log(user.api_token) +}) +``` + + + + +```bash +curl -L -X POST '/admin/users/' \\ +-H 'Cookie: connect.sid={sid}' \\ +-H 'Content-Type: application/json' \\ +--data-raw '{ + "api_token": "{api_token}" +}' +``` + + + + +Then, initialize the Medusa client passing it the `apiKey` option: + +```ts +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, + apiKey: "{api_token}", +}) +``` + +--- + +## Publishable API Key + +Publishable API Keys allow you to send a request to Store API routes with a pre-defined scope. You can associate the publishable API key with one or more resources, such as sales channels, then include the publishable API key in the header of your requests. + +The Medusa backend will infer the scope of the current request based on the publishable API key. At the moment, publishable API keys only work with sales channels. + +It's highly recommended to create a publishable API key and pass it as an initialization option of the Medusa client. + +You can learn more about publishable API keys and how to use them in [this documentation](../development/publishable-api-keys/index.mdx). + +### Create a Publishable API Key + +You can create a publishable API key either using the [admin REST APIs](../development/publishable-api-keys/admin/manage-publishable-api-keys.mdx), or using the [Medusa admin dashboard](../user-guide/settings/publishable-api-keys.mdx). + +### Use a Publishable API Key + +To use the publishable API key, pass it as an option to the Medusa client: + +```ts +const medusa = new Medusa({ + maxRetries: 3, + baseUrl: "https://api.example.com", + publishableApiKey, +}) +``` + +--- + +## HTTP Compression + +If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the `x-no-compression` header in the `customHeaders` parameter which is available in all methods. + +For example: + +```ts +medusa.products.list({}, { + "x-no-compression": true, +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +--- + +## Expanding Fields + +In many methods you'll find an `expand` property that can be accepted within one of the method's parameters. You can use the `expand` property to unpack an entity's relations and return them in the response. + +:::warning + +The relations you pass to `expand` replace any relations that are expanded by default in the request. + +::: + +### Expanding One Relation + +For example, when you retrieve products, you can retrieve their collection by passing to the `expand` query parameter the value `collection`: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + expand: "collection", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +### Expanding Multiple Relations + +You can expand more than one relation by separating the relations in the `expand` query parameter with a comma. + +For example, to retrieve both the variants and the collection of products, pass to the `expand` query parameter the value `variants,collection`: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + expand: "variants,collection", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +### Prevent Expanding Relations + +Some requests expand relations by default. You can prevent that by passing +an empty expand value to retrieve an entity without any extra relations. + +For example: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + expand: "", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +This would retrieve each product with only its properties, without any +relations like `collection`. + +--- + +## Selecting Fields + +In many methods you'll find a `fields` property that can be accepted within one of the method's parameters. You can use the `fields` property to specify which +fields in the entity should be returned in the response. + +:::warning + +If you pass a `fields` query parameter, only the fields you +pass in the value along with the `id` of the entity will be returned in the +response. + +::: + + +The `fields` query parameter does not affect the expanded relations. You'll have to use the [Expand parameter](#expanding-fields) instead. + + +### Selecting One Field + +For example, when you retrieve a list of products, you can retrieve only the titles of the products by passing `title` as a value to the `fields` query parameter: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + fields: "title", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +As mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter. + +You can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + fields: "title", + expand: "", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +### Selecting Multiple Fields + +You can pass more than one field by seperating the field names in the `fields` query parameter with a comma. + +For example, to select the `title` and `handle` of products: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + fields: "title,handle", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +### Retrieve Only the ID + +You can pass an empty `fields` query parameter to return only the ID of an entity. + +For example: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + fields: "", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +You can also pair with an empty `expand` query parameter to ensure that the +relations aren't retrieved as well. For example: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + fields: "", + expand: "", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +--- + +## Pagination + +### Query Parameters + +In listing methods, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`. + +`limit` is used to specify the maximum number of items that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities. + +You can use the `offset` query parameter to change between pages. For example, if the limit is `50`, at page one the offset should be `0`; at page two the offset should be `50`, and so on. + +For example, to limit the number of products returned in the list products method: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + limit: 5, +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +### Response Fields + +In the response of listing methods, aside from the entities retrieved, +there are three pagination-related fields returned: + +- `limit`: the maximum number of items that can be returned in the response. +- `offset`: the number of items that were skipped before the entities in the result. +- `count`: the total number of available items of this entity. It can be used to determine how many pages are there. + +For example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`. + +### Sort Order + +The `order` field available on methods supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their `created_at` attribute by setting `order` to `created_at`: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + order: "created_at", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +By default, the sort direction will be ascending. To change it to descending, pass a dash (`-`) before the attribute name. For example: + +```ts +import Medusa from "@medusajs/medusa-js" +const medusa = new Medusa({ + baseUrl: MEDUSA_BACKEND_URL, + maxRetries: 3, +}) +// must be previously logged in or use api token +medusa.admin.products.list({ + order: "-created_at", +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}) +``` + +This sorts the products by their `created_at` attribute in the descending order. diff --git a/www/apps/docs/content/medusa-react/overview.mdx b/www/apps/docs/content/medusa-react/overview.mdx index 44f40a0f5b..cca6839366 100644 --- a/www/apps/docs/content/medusa-react/overview.mdx +++ b/www/apps/docs/content/medusa-react/overview.mdx @@ -11,7 +11,7 @@ import TabItem from '@theme/TabItem'; :::tip -Alternatively, you can use Medusa’s [JS Client](../js-client/overview.md) or the [REST APIs](https://docs.medusajs.com/api/store). +Alternatively, you can use Medusa’s [JS Client](../js-client/overview.mdx) or the [REST APIs](https://docs.medusajs.com/api/store). ::: diff --git a/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx b/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx index 3c5a58fa6f..72c9d935e8 100644 --- a/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx +++ b/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx @@ -36,7 +36,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx b/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx index fea8662d9b..d429ffe512 100644 --- a/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx +++ b/www/apps/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx @@ -36,7 +36,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/customers/admin/manage-customer-groups.mdx b/www/apps/docs/content/modules/customers/admin/manage-customer-groups.mdx index 0d4e3416c8..0906a1925b 100644 --- a/www/apps/docs/content/modules/customers/admin/manage-customer-groups.mdx +++ b/www/apps/docs/content/modules/customers/admin/manage-customer-groups.mdx @@ -30,7 +30,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/customers/admin/manage-customers.mdx b/www/apps/docs/content/modules/customers/admin/manage-customers.mdx index c882e37d49..35fba53dac 100644 --- a/www/apps/docs/content/modules/customers/admin/manage-customers.mdx +++ b/www/apps/docs/content/modules/customers/admin/manage-customers.mdx @@ -34,7 +34,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, JavaScript’s Fetch API, or cURL. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/customers/storefront/implement-customer-profiles.mdx b/www/apps/docs/content/modules/customers/storefront/implement-customer-profiles.mdx index 136ca16221..1401cb3840 100644 --- a/www/apps/docs/content/modules/customers/storefront/implement-customer-profiles.mdx +++ b/www/apps/docs/content/modules/customers/storefront/implement-customer-profiles.mdx @@ -44,7 +44,7 @@ It's also assumed you already have a storefront set up. It can be a custom store This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/discounts/admin/manage-discounts.mdx b/www/apps/docs/content/modules/discounts/admin/manage-discounts.mdx index a1b70b14d3..d46405b08d 100644 --- a/www/apps/docs/content/modules/discounts/admin/manage-discounts.mdx +++ b/www/apps/docs/content/modules/discounts/admin/manage-discounts.mdx @@ -46,7 +46,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, JavaScript’s Fetch API, or cURL. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/discounts/storefront/use-discounts-in-checkout.mdx b/www/apps/docs/content/modules/discounts/storefront/use-discounts-in-checkout.mdx index f94b7357ee..d446bb200a 100644 --- a/www/apps/docs/content/modules/discounts/storefront/use-discounts-in-checkout.mdx +++ b/www/apps/docs/content/modules/discounts/storefront/use-discounts-in-checkout.mdx @@ -40,7 +40,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx b/www/apps/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx index 646aebd75d..c76105a20d 100644 --- a/www/apps/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx +++ b/www/apps/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx @@ -39,7 +39,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx b/www/apps/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx index f011f21150..6882845236 100644 --- a/www/apps/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx +++ b/www/apps/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx @@ -36,7 +36,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/multiwarehouse/admin/manage-inventory-items.mdx b/www/apps/docs/content/modules/multiwarehouse/admin/manage-inventory-items.mdx index ee07edff0a..ef2436417f 100644 --- a/www/apps/docs/content/modules/multiwarehouse/admin/manage-inventory-items.mdx +++ b/www/apps/docs/content/modules/multiwarehouse/admin/manage-inventory-items.mdx @@ -39,7 +39,7 @@ Furthermore, inventory levels are tied to a location ID. So, it’s recommended This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/multiwarehouse/admin/manage-item-allocations-in-orders.mdx b/www/apps/docs/content/modules/multiwarehouse/admin/manage-item-allocations-in-orders.mdx index 41ad35634d..320f7f241e 100644 --- a/www/apps/docs/content/modules/multiwarehouse/admin/manage-item-allocations-in-orders.mdx +++ b/www/apps/docs/content/modules/multiwarehouse/admin/manage-item-allocations-in-orders.mdx @@ -50,7 +50,7 @@ This guide assumes you have a stock location and inventory modules installed. Yo This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/multiwarehouse/admin/manage-reservations.mdx b/www/apps/docs/content/modules/multiwarehouse/admin/manage-reservations.mdx index 539622a55b..4345576f13 100644 --- a/www/apps/docs/content/modules/multiwarehouse/admin/manage-reservations.mdx +++ b/www/apps/docs/content/modules/multiwarehouse/admin/manage-reservations.mdx @@ -51,7 +51,7 @@ This guide assumes you have a stock location and inventory modules installed. Yo This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/multiwarehouse/admin/manage-stock-locations.mdx b/www/apps/docs/content/modules/multiwarehouse/admin/manage-stock-locations.mdx index f7f4bd2e39..0d769691fa 100644 --- a/www/apps/docs/content/modules/multiwarehouse/admin/manage-stock-locations.mdx +++ b/www/apps/docs/content/modules/multiwarehouse/admin/manage-stock-locations.mdx @@ -41,7 +41,7 @@ This guide assumes you have a stock location module installed. You can use Medus This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/admin/edit-order.mdx b/www/apps/docs/content/modules/orders/admin/edit-order.mdx index d391fec35d..853c0fa670 100644 --- a/www/apps/docs/content/modules/orders/admin/edit-order.mdx +++ b/www/apps/docs/content/modules/orders/admin/edit-order.mdx @@ -56,7 +56,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/admin/manage-claims.mdx b/www/apps/docs/content/modules/orders/admin/manage-claims.mdx index 6b7bc694d0..6340eb7daa 100644 --- a/www/apps/docs/content/modules/orders/admin/manage-claims.mdx +++ b/www/apps/docs/content/modules/orders/admin/manage-claims.mdx @@ -40,7 +40,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/admin/manage-draft-orders.mdx b/www/apps/docs/content/modules/orders/admin/manage-draft-orders.mdx index 565a08f40e..030953b5ee 100644 --- a/www/apps/docs/content/modules/orders/admin/manage-draft-orders.mdx +++ b/www/apps/docs/content/modules/orders/admin/manage-draft-orders.mdx @@ -34,7 +34,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/admin/manage-orders.mdx b/www/apps/docs/content/modules/orders/admin/manage-orders.mdx index 6c5df5dc86..47a190904d 100644 --- a/www/apps/docs/content/modules/orders/admin/manage-orders.mdx +++ b/www/apps/docs/content/modules/orders/admin/manage-orders.mdx @@ -42,7 +42,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/admin/manage-returns.mdx b/www/apps/docs/content/modules/orders/admin/manage-returns.mdx index 75b88b01c7..b723f4017c 100644 --- a/www/apps/docs/content/modules/orders/admin/manage-returns.mdx +++ b/www/apps/docs/content/modules/orders/admin/manage-returns.mdx @@ -35,7 +35,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/admin/manage-swaps.mdx b/www/apps/docs/content/modules/orders/admin/manage-swaps.mdx index 516d647b59..3b884088f3 100644 --- a/www/apps/docs/content/modules/orders/admin/manage-swaps.mdx +++ b/www/apps/docs/content/modules/orders/admin/manage-swaps.mdx @@ -41,7 +41,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/storefront/create-return.mdx b/www/apps/docs/content/modules/orders/storefront/create-return.mdx index 78ce31e2aa..594c75993c 100644 --- a/www/apps/docs/content/modules/orders/storefront/create-return.mdx +++ b/www/apps/docs/content/modules/orders/storefront/create-return.mdx @@ -41,7 +41,7 @@ It's also assumed you already have a storefront set up. It can be a custom store This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/storefront/create-swap.mdx b/www/apps/docs/content/modules/orders/storefront/create-swap.mdx index aea1e74cf3..df3526650a 100644 --- a/www/apps/docs/content/modules/orders/storefront/create-swap.mdx +++ b/www/apps/docs/content/modules/orders/storefront/create-swap.mdx @@ -36,7 +36,7 @@ It's also assumed you already have a storefront set up. It can be a custom store This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/storefront/handle-order-edits.mdx b/www/apps/docs/content/modules/orders/storefront/handle-order-edits.mdx index 5c033b4566..5887140197 100644 --- a/www/apps/docs/content/modules/orders/storefront/handle-order-edits.mdx +++ b/www/apps/docs/content/modules/orders/storefront/handle-order-edits.mdx @@ -54,7 +54,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/storefront/implement-claim-order.mdx b/www/apps/docs/content/modules/orders/storefront/implement-claim-order.mdx index 74c1619303..d261e036dc 100644 --- a/www/apps/docs/content/modules/orders/storefront/implement-claim-order.mdx +++ b/www/apps/docs/content/modules/orders/storefront/implement-claim-order.mdx @@ -51,7 +51,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/orders/storefront/retrieve-order-details.mdx b/www/apps/docs/content/modules/orders/storefront/retrieve-order-details.mdx index 4caa61e165..0dcdd820f1 100644 --- a/www/apps/docs/content/modules/orders/storefront/retrieve-order-details.mdx +++ b/www/apps/docs/content/modules/orders/storefront/retrieve-order-details.mdx @@ -22,7 +22,7 @@ It's also assumed you already have a storefront set up. It can be a custom store This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/price-lists/admin/_import-prices.mdx b/www/apps/docs/content/modules/price-lists/admin/_import-prices.mdx index bc9308d244..35a91fcb4a 100644 --- a/www/apps/docs/content/modules/price-lists/admin/_import-prices.mdx +++ b/www/apps/docs/content/modules/price-lists/admin/_import-prices.mdx @@ -119,7 +119,7 @@ No This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/price-lists/admin/manage-price-lists.mdx b/www/apps/docs/content/modules/price-lists/admin/manage-price-lists.mdx index f9f4fe2353..85e87b29a0 100644 --- a/www/apps/docs/content/modules/price-lists/admin/manage-price-lists.mdx +++ b/www/apps/docs/content/modules/price-lists/admin/manage-price-lists.mdx @@ -26,7 +26,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, JavaScript’s Fetch API, or cURL. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and [have created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and [have created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/products/admin/import-products.mdx b/www/apps/docs/content/modules/products/admin/import-products.mdx index 002c6fadec..50fdfe8df4 100644 --- a/www/apps/docs/content/modules/products/admin/import-products.mdx +++ b/www/apps/docs/content/modules/products/admin/import-products.mdx @@ -848,7 +848,7 @@ No This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/products/admin/manage-categories.mdx b/www/apps/docs/content/modules/products/admin/manage-categories.mdx index 58123f220f..48875ae456 100644 --- a/www/apps/docs/content/modules/products/admin/manage-categories.mdx +++ b/www/apps/docs/content/modules/products/admin/manage-categories.mdx @@ -33,7 +33,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/products/admin/manage-products.mdx b/www/apps/docs/content/modules/products/admin/manage-products.mdx index f48bdbc5e0..2954810623 100644 --- a/www/apps/docs/content/modules/products/admin/manage-products.mdx +++ b/www/apps/docs/content/modules/products/admin/manage-products.mdx @@ -34,7 +34,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/products/storefront/show-products.mdx b/www/apps/docs/content/modules/products/storefront/show-products.mdx index 5a2a95a9a2..a63835421f 100644 --- a/www/apps/docs/content/modules/products/storefront/show-products.mdx +++ b/www/apps/docs/content/modules/products/storefront/show-products.mdx @@ -38,7 +38,7 @@ It's also assumed you already have a storefront set up. It can be a custom store This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/products/storefront/use-categories.mdx b/www/apps/docs/content/modules/products/storefront/use-categories.mdx index 6fbf9343b2..11208c6077 100644 --- a/www/apps/docs/content/modules/products/storefront/use-categories.mdx +++ b/www/apps/docs/content/modules/products/storefront/use-categories.mdx @@ -36,7 +36,7 @@ It's also assumed you already have a storefront set up. It can be a custom store This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx b/www/apps/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx index e0752c47ea..676cc247f8 100644 --- a/www/apps/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx +++ b/www/apps/docs/content/modules/regions-and-currencies/admin/manage-currencies.mdx @@ -42,7 +42,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/regions-and-currencies/admin/manage-regions.mdx b/www/apps/docs/content/modules/regions-and-currencies/admin/manage-regions.mdx index 8171a47d6e..6c46a1c987 100644 --- a/www/apps/docs/content/modules/regions-and-currencies/admin/manage-regions.mdx +++ b/www/apps/docs/content/modules/regions-and-currencies/admin/manage-regions.mdx @@ -42,7 +42,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/regions-and-currencies/storefront/use-regions.mdx b/www/apps/docs/content/modules/regions-and-currencies/storefront/use-regions.mdx index ff8db113d7..88697869f9 100644 --- a/www/apps/docs/content/modules/regions-and-currencies/storefront/use-regions.mdx +++ b/www/apps/docs/content/modules/regions-and-currencies/storefront/use-regions.mdx @@ -36,7 +36,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/sales-channels/admin/manage.mdx b/www/apps/docs/content/modules/sales-channels/admin/manage.mdx index 63f57c3586..8234682180 100644 --- a/www/apps/docs/content/modules/sales-channels/admin/manage.mdx +++ b/www/apps/docs/content/modules/sales-channels/admin/manage.mdx @@ -34,7 +34,7 @@ It's assumed that you already have a Medusa backend installed and set up. If not This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and [have created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and [have created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/sales-channels/storefront/use-sales-channels.mdx b/www/apps/docs/content/modules/sales-channels/storefront/use-sales-channels.mdx index 89dd86f497..269ff74540 100644 --- a/www/apps/docs/content/modules/sales-channels/storefront/use-sales-channels.mdx +++ b/www/apps/docs/content/modules/sales-channels/storefront/use-sales-channels.mdx @@ -39,7 +39,7 @@ It is also assumed you already have a storefront set up. It can be a custom stor This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.mdx) and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/taxes/admin/manage-tax-rates.mdx b/www/apps/docs/content/modules/taxes/admin/manage-tax-rates.mdx index 6720f0be42..c9da76a803 100644 --- a/www/apps/docs/content/modules/taxes/admin/manage-tax-rates.mdx +++ b/www/apps/docs/content/modules/taxes/admin/manage-tax-rates.mdx @@ -33,7 +33,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/taxes/admin/manage-tax-settings.mdx b/www/apps/docs/content/modules/taxes/admin/manage-tax-settings.mdx index 77efd1227c..af59a5037a 100644 --- a/www/apps/docs/content/modules/taxes/admin/manage-tax-settings.mdx +++ b/www/apps/docs/content/modules/taxes/admin/manage-tax-settings.mdx @@ -34,7 +34,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/users/admin/manage-invites.mdx b/www/apps/docs/content/modules/users/admin/manage-invites.mdx index 36ad528584..af023d81d8 100644 --- a/www/apps/docs/content/modules/users/admin/manage-invites.mdx +++ b/www/apps/docs/content/modules/users/admin/manage-invites.mdx @@ -36,7 +36,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/users/admin/manage-profile.mdx b/www/apps/docs/content/modules/users/admin/manage-profile.mdx index c2700386da..a28d1c6657 100644 --- a/www/apps/docs/content/modules/users/admin/manage-profile.mdx +++ b/www/apps/docs/content/modules/users/admin/manage-profile.mdx @@ -32,7 +32,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, JavaScript’s Fetch API, or cURL. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/modules/users/admin/manage-users.mdx b/www/apps/docs/content/modules/users/admin/manage-users.mdx index e113cfacc8..1ada7c8363 100644 --- a/www/apps/docs/content/modules/users/admin/manage-users.mdx +++ b/www/apps/docs/content/modules/users/admin/manage-users.mdx @@ -35,7 +35,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. -If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#configuration). ### Medusa React diff --git a/www/apps/docs/content/storefront/roadmap.mdx b/www/apps/docs/content/storefront/roadmap.mdx index 33c3304f20..68691fb8f2 100644 --- a/www/apps/docs/content/storefront/roadmap.mdx +++ b/www/apps/docs/content/storefront/roadmap.mdx @@ -28,7 +28,7 @@ You can instead follow this recipe that will guide you through implementing feat The storefront connects to the backend to retrieve and process data. You can use different tools or libraries when connecting your storefront to the backend. - **For React-based storefronts:** you can use [Medusa React](../medusa-react/overview.mdx). It provides you with the necessary hooks to retrieve or manipulate data on your backend. -- **For JavaScript frameworks:** you can use [Medusa’s JavaScript Client](../js-client/overview.md) in any JavaScript framework. This NPM package facilitates interacting with the backend’s REST APIs. +- **For JavaScript frameworks:** you can use [Medusa’s JavaScript Client](../js-client/overview.mdx) in any JavaScript framework. This NPM package facilitates interacting with the backend’s REST APIs. - **For other frontend technologies:** you can interact directly with the Medusa backend by sending requests to its [Store REST APIs](https://docs.medusajs.com/api/store). :::tip diff --git a/www/apps/docs/src/components/ParameterTypes/Items/index.tsx b/www/apps/docs/src/components/ParameterTypes/Items/index.tsx index 139689b0e6..0a7c1063f8 100644 --- a/www/apps/docs/src/components/ParameterTypes/Items/index.tsx +++ b/www/apps/docs/src/components/ParameterTypes/Items/index.tsx @@ -1,8 +1,21 @@ -import { DetailsSummary, InlineCode, MarkdownContent } from "docs-ui" +import { + Badge, + DetailsSummary, + ExpandableNotice, + FeatureFlagNotice, + InlineCode, + MarkdownContent, +} from "docs-ui" import React from "react" import Details from "../../../theme/Details" import clsx from "clsx" import { Parameter } from ".." +import { + ArrowDownLeftMini, + ArrowsPointingOutMini, + TriangleRightMini, +} from "@medusajs/icons" +import IconFlagMini from "../../../theme/Icon/FlagMini" type ParameterTypesItemsProps = { parameters: Parameter[] @@ -13,17 +26,48 @@ const ParameterTypesItems = ({ parameters, level = 1, }: ParameterTypesItemsProps) => { + function getGroupName() { + switch (level) { + case 1: + return "group/parameterOne" + case 2: + return "group/parameterTwo" + case 3: + return "group/parameterThree" + case 4: + return "group/parameterFour" + } + } + function getBorderForGroupName() { + switch (level) { + case 1: + return "group-open/parameterOne:border-solid group-open/parameterOne:border-0 group-open/parameterOne:border-b" + case 2: + return "group-open/parameterTwo:border-solid group-open/parameterTwo:border-0 group-open/parameterTwo:border-b" + case 3: + return "group-open/parameterThree:border-solid group-open/parameterThree:border-0 group-open/parameterThree:border-b" + case 4: + return "group-open/parameterFour:border-solid group-open/parameterFour:border-0 group-open/parameterFour:border-b" + } + } + function getRotateForGroupName() { + switch (level) { + case 1: + return "group-open/parameterOne:rotate-90" + case 2: + return "group-open/parameterTwo:rotate-90" + case 3: + return "group-open/parameterThree:rotate-90" + case 4: + return "group-open/parameterFour:rotate-90" + } + } function getItemClassNames(details = true) { return clsx( - level < 3 && [ - "odd:[&:not(:first-child):not(:last-child)]:!border-y last:not(:first-child):!border-t", - "first:!border-t-0 first:not(:last-child):!border-b last:!border-b-0 even:!border-y-0", - ], - details && level == 1 && `group/parameter`, - !details && - level == 1 && - `group-open/parameter:border-solid group-open/parameter:border-0 group-open/parameter:border-b`, - level >= 3 && "!border-0" + "odd:[&:not(:first-child):not(:last-child)]:!border-y last:not(:first-child):!border-t", + "first:!border-t-0 first:not(:last-child):!border-b last:!border-b-0 even:!border-y-0", + details && getGroupName(), + !details && getBorderForGroupName() ) } function getSummary(parameter: Parameter, key: number, nested = true) { @@ -48,16 +92,15 @@ const ParameterTypesItems = ({ ) : undefined } expandable={parameter.children?.length > 0} + hideExpandableIcon={true} className={clsx( getItemClassNames(false), - level < 3 && "!p-1", - !nested && "cursor-default", - level >= 3 && [ - "pl-1 mt-1", - "mx-1 relative before:content-[''] before:h-full before:w-0.25", - "before:absolute before:top-0 before:left-0", - "before:bg-medusa-fg-muted before:rounded-full", - ] + "py-1 pr-1", + level === 1 && "pl-1", + level === 2 && "pl-3", + level === 3 && "pl-[120px]", + level === 4 && "pl-[160px]", + !nested && "cursor-default" )} onClick={(e) => { const targetElm = e.target as HTMLElement @@ -68,35 +111,63 @@ const ParameterTypesItems = ({ } }} > -
- {parameter.name} - - - {parameter.type} - - - {parameter.optional === false && ( - + {nested && ( + - Required - + /> )} + {!nested && level > 1 && ( + + )} +
+ {parameter.name} + + + {parameter.type} + + + {parameter.optional === false && ( + + Required + + )} + {parameter.featureFlag && ( + + } + /> + )} + {parameter.expandable && ( + } + /> + )} +
) } return ( -
1 && "bg-docs-bg-surface rounded", - level >= 3 && "mb-1" - )} - > +
{parameters.map((parameter, key) => { return ( <> diff --git a/www/apps/docs/src/components/ParameterTypes/index.tsx b/www/apps/docs/src/components/ParameterTypes/index.tsx index 388917fad6..ca30bd8e39 100644 --- a/www/apps/docs/src/components/ParameterTypes/index.tsx +++ b/www/apps/docs/src/components/ParameterTypes/index.tsx @@ -8,6 +8,8 @@ export type Parameter = { optional?: boolean defaultValue?: string description?: string + featureFlag?: string + expandable: boolean children?: Parameter[] } @@ -22,7 +24,7 @@ const ParameterTypes = ({ }: ParameterTypesType) => { return (
diff --git a/www/apps/docs/src/theme/Icon/FlagMini/index.tsx b/www/apps/docs/src/theme/Icon/FlagMini/index.tsx new file mode 100644 index 0000000000..bd3948f640 --- /dev/null +++ b/www/apps/docs/src/theme/Icon/FlagMini/index.tsx @@ -0,0 +1,27 @@ +import { IconProps } from "@medusajs/icons/dist/types" +import clsx from "clsx" +import React from "react" + +const IconFlagMini = (props: IconProps) => { + return ( + + + + ) +} + +export default IconFlagMini diff --git a/www/apps/docs/src/theme/Icon/index.tsx b/www/apps/docs/src/theme/Icon/index.tsx index 523ce95dfd..c02911ee04 100644 --- a/www/apps/docs/src/theme/Icon/index.tsx +++ b/www/apps/docs/src/theme/Icon/index.tsx @@ -101,6 +101,7 @@ import { } from "@medusajs/icons" import IconPuzzleSolid from "./PuzzleSolid" import IconNextjs from "./Nextjs" +import IconFlagMini from "./FlagMini" export default { "academic-cap-solid": AcademicCapSolid, @@ -159,6 +160,7 @@ export default { "folder-open": FolderOpen, gatsby: Gatsby, "gift-solid": GiftSolid, + "flag-mini": IconFlagMini, github: Github, "globe-europe": GlobeEurope, "globe-europe-solid": GlobeEuropeSolid, diff --git a/www/packages/docs-ui/src/components/Details/Summary/index.tsx b/www/packages/docs-ui/src/components/Details/Summary/index.tsx index dc0ecfe5a9..2a8689a303 100644 --- a/www/packages/docs-ui/src/components/Details/Summary/index.tsx +++ b/www/packages/docs-ui/src/components/Details/Summary/index.tsx @@ -10,6 +10,7 @@ export type DetailsSummaryProps = { open?: boolean className?: string titleClassName?: string + hideExpandableIcon?: boolean } & Omit, "title"> export const DetailsSummary = ({ @@ -21,6 +22,7 @@ export const DetailsSummary = ({ open = false, className, titleClassName, + hideExpandableIcon = false, ...rest }: DetailsSummaryProps) => { return ( @@ -54,7 +56,7 @@ export const DetailsSummary = ({ {(badge || expandable) && ( {badge} - {expandable && ( + {expandable && !hideExpandableIcon && ( diff --git a/www/packages/docs-ui/src/components/ExpandableNotice/index.tsx b/www/packages/docs-ui/src/components/ExpandableNotice/index.tsx new file mode 100644 index 0000000000..87f733dc73 --- /dev/null +++ b/www/packages/docs-ui/src/components/ExpandableNotice/index.tsx @@ -0,0 +1,34 @@ +import React from "react" +import { Badge, Link, Tooltip } from "@/components" + +export type ExpandableNoticeProps = { + type: "request" | "method" + link: string + badgeContent?: React.ReactNode + badgeClassName?: string +} + +export const ExpandableNotice = ({ + type = "request", + link, + badgeContent = "expendable", + badgeClassName, +}: ExpandableNoticeProps) => { + return ( + + If this {type} accepts an expand{" "} + {type === "request" ? "parameter" : "property or option"}, +
this field can be expanded into an + object. + + } + clickable + > + + {badgeContent} + + + ) +} diff --git a/www/packages/docs-ui/src/components/FeatureFlagNotice/index.tsx b/www/packages/docs-ui/src/components/FeatureFlagNotice/index.tsx new file mode 100644 index 0000000000..735ac836c2 --- /dev/null +++ b/www/packages/docs-ui/src/components/FeatureFlagNotice/index.tsx @@ -0,0 +1,40 @@ +import React from "react" +import { Badge, Link, Tooltip } from "@/components" + +export type FeatureFlagNoticeProps = { + featureFlag: string + type?: "endpoint" | "parameter" + tooltipTextClassName?: string + badgeClassName?: string + badgeContent?: React.ReactNode +} + +export const FeatureFlagNotice = ({ + featureFlag, + type = "endpoint", + tooltipTextClassName, + badgeClassName, + badgeContent = "feature flag", +}: FeatureFlagNoticeProps) => { + return ( + + To use this {type}, make sure to +
+ + enable its feature flag: {featureFlag} + + + } + clickable + > + + {badgeContent} + + + ) +} diff --git a/www/packages/docs-ui/src/components/index.ts b/www/packages/docs-ui/src/components/index.ts index 032c983ffa..c6402636b9 100644 --- a/www/packages/docs-ui/src/components/index.ts +++ b/www/packages/docs-ui/src/components/index.ts @@ -11,6 +11,8 @@ export * from "./CodeTabs" export * from "./CopyButton" export * from "./Details" export * from "./Details/Summary" +export * from "./ExpandableNotice" +export * from "./FeatureFlagNotice" export * from "./Feedback" export * from "./Feedback/Solutions" export * from "./Icons"