Noticed that `RequestQueryFields` is defined in both the `medusa` and `types` package. Within the `medusa` package sometimes it uses the local type definition or the definition in `types`.
This PR removes the type definition of `RequestQueryFields` in `medusa` and uses that in `types` instead.
* fix(medusa-oas-cli, oas-github-ci): updated paths to docs directories following monorepo reorganization
* revert change to workspaces
* change oas in workspaces
* revert change in test script
Fix `node-gyp` error that occurs during installation when using NPM and 20+ versions of Node.js. The error results from the package `@stdlib/number-float64-base-normalize` which is a dependency of `@segment/analytics-next`. Installing v0.0.8 resolves the error.
More details in PR #6485
## Testing
To test out the fix:
1. In a Medusa backend, remove the installation of `@stdlib/number-float64-base-normalize` (if available) and add instead the following override:
```json
"overrides": {
"@medusajs/admin": {
"@medusajs/admin-ui": "2.1.14-snapshot-20240405070935"
}
}
```
2. Remove node_modules + any previous package-lock.json
3. Change to node v20+ and use npm to install dependencies -> no error occurs during installation.
## What
Adds a `--verbose` option that shows the output of all underlying processes in real-time.
## Why
This is helpful for testing and debugging issues, especially issues that the community runs into. We can ask community members to pass the `--verbose` option and provide us with the outputted logs if they face problems.
## Caveats
When installing the Next.js starter then terminating the process, the main and child processes don't receive the abort signal as it seems to occur in the child process. This leads to the command continuing but then running into an error in the next step.
As this option is only used for debugging, I don't think it's a big issue.
## Testing
Run the `create-medusa-app` snapshot below with `--verbose` option. Or, change to the `packages/create-medusa-app` directory and run:
```bash
yarn dev --directory-path ~/some-dir --verbose
```
> The `--directory-path` option in this case is necessary as installing the medusa backend in the current `packages/create-medusa-app` directory leads to errors related to yarn workspaces.
## What
Adds an AI generator to the docblock tool that uses OpenAI.
The generator at the moment only generates examples for functions when the `--generate-examples` option is provided.
## Note
I've included the generated examples of the `IOrderModuleService` as a reference of the type of result provided by the AI generator, with minor tweeks I've made. I haven't made any changes to descriptions in that file.
- Added new documentation page for Medusa Worker.
- Updated Railway deployment guide with details on Medusa Worker.
- Small adjustments to the `worker_mode` option's TSDocs.
## What
Added a `--v2` option to the `create-medusa-app` command that clones the [feat/v2](https://github.com/medusajs/medusa-starter-default/pull/150) branch of the starter default and makes minor changes to the setup process.
## Why
This option is supposed to make it easier to test out internally a Medusa setup with all the commerce modules. The starter's branch installs and configures the modules + the V2 feature flag.
## Testing
To test it out, run the snapshot with the `--v2` option.
## Notes
- I couldn't install the new admin dashboard in the starter branch as it's not on NPM yet (at the time of writing this), so at the moment, this opens the current admin dashboard instead.
- When trying to create an invite using the CLI tool I get the error `Unable to resolve inviteService`. Not sure if we should also make changes to the CLI tool to allow creating an invite when V2 is enabled (I know now invites are creating within the User Module, so maybe when the V2 feature flag is enabled that should be resolved instead), but for now I just disabled running the create invite command as this is mainly for internal testing. Let me know what the suggested approach is here.
This PR includes documentation that preps for v2 docs (but doesn't introduce new docs).
_Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._
## Changes
- Change Medusa version in base OAS used for v2.
- Fix to docblock generator related to not catching all path parameters.
- Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules.
- Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used.
- Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment.
- Upgraded docusaurus to v3.0.1
- Added new Vale rules to ensure correct spelling of Medusa Admin and module names.
- Added new components to the `docs-ui` package that will be used in future documentation changes.
Generated TSDocs for the past release.
Note: I haven't updated examples as the examples are for modules without a public reference yet, so the examples can wait.
* docs: add missing widget props for collections injection zones
Adds missing widget props for the `product_collection.details.before` and `product_collection.details.after` injection zones.
* fix lint error
During the merge of #6338 the imports in the `git-manager.ts` causes an error during build which wasn't caught in the merge. This PR fixes the imports in the file.
- Fixed CORS middleware to account for routes of a single path (for example, `/custom` and not just `/custom/test`).
- Added a troubleshooting guide for admin webpack errors (see issue #6375)
- Creates a script that runs the `yarn changeset --empty` command if there are file changes. This is important to not create PRs of just empty changesets if there are no file changes.
- Run script in all docs-generation PRs
- Fix to condition in `generate-docblock` action
## What
This PR adds support for generating OAS in the docblock generator tool.
## How
As OAS are generated in a different manner/location than regular TSDocs, it requires a new type of generator within the tool. As such, the existing docblock generator now only handles files that aren't under the `packages/medusa/src/api` and `packages/medusa/src/api-v2` directories. The new generator handles files under these directories. However, it only considers a node to be an API route if it's a function having two parameters of types `MedusaRequest` and `MedusaResponse` respectively. So, only new API Routes are considered.
The new generator runs the same way as the existing docblock generator with the same method. The generators will detect whether they can run on the file or not and the docblocks/oas are generated based on that. I've also added a `--type` option to the CLI commands of the docblock generator tool to further filter and choose which generator to use.
When the OAS generator finds an API route, it will generate its OAS under the `docs-util/oas-output/operations` directory in a TypeScript file. I chose to generate in TS files rather than YAML files to maintain the functionality of `medusa-oas` without major changes.
Schemas detected in the OAS operation, such as the request and response schemas, are generated as OAS schemas under the `docs-util/oas-output/schemas` directory and referenced in operations and other resources.
The OAS generator also handles updating OAS. When you run the same command on a file/directory and an API route already has OAS associated with it, its information and associated schemas are updated instead of generating new schemas/operations. However, summaries and descriptions aren't updated unless they're not available or their values are the default value SUMMARY.
## API Route Handling
### Request and Response Types
The tool extracts the type of request/response schemas from the type arguments passed to the `MedusaRequest` and `MedusaResponse` respectively. For example:
```ts
export const POST = async (
req: MedusaRequest<{
id: string
}>,
res: MedusaResponse<ResponseType>
) => {
// ...
}
```
If these types aren't provided, the request/response is considered empty.
### Path Parameters
Path parameters are extracted from the file's path name. For example, for `packages/medusa/src/api-v2/admin/campaigns/[id]/route.ts` the `id` path parameter is extracted.
### Query Parameters
The tool extracts the query parameters of an API route based on the type of `request.validatedQuery`. Once we narrow down how we're typing query parameters, we can revisit this implementation.
## Changes to Medusa Oas CLI
I added a `--v2` option to the Medusa OAS CLI to support loading OAS from `docs-util/oas-output` directory rather than the `medusa` package. This will output the OAS in `www/apps/api-reference/specs`, wiping out old OAS. This is only helpful for testing purposes to check how the new OAS looks like in the API reference. It also allows us to slowly start adapting the new OAS.
## Other Notes and Changes
- I've added a GitHub action that creates a PR for generated OAS when Version Packages is merged (similar to regular TSDocs). However, this will only generate the OAS in the `docs-util/oas-output` directory and will not affect the existing OAS in the API reference. Once we're ready to include it those OAS, we can talk about next steps.
- I've moved the base YAML from the `medusa` package to the `docs-util/oas-output/base` directory and changed the `medusa-oas` tool to load them from there.
- I added a `clean:oas` command to the docblock generator CLI tool that removes unused OAS operations, schemas, and tags from `docs-util/oas-output`. The tool also supports updating OAS operations and their associated schemas. However, I didn't add a specific mechanism to update schemas on their own as that's a bit tricky and would require the help of typedoc. I believe with the process of running the tool on the `api-v2` directory whenever there's a new release should be enough to update associated schemas, but if we find that not enough, we can revisit updating schemas individually.
- Because of the `clean:oas` command which makes changes to tags (removing the existing ones, more details on this one later), I've added new base YAML under `docs-util/oas-output/base-v2`. This is used by the tool when generating/cleaning OAS, and the Medusa OAS CLI when the `--v2` option is used.
## Testing
### Prerequisites
To test with request/response types, I recommend minimally modifying `packages/medusa/src/types/routing.ts` to allow type arguments of `MedusaRequest` and `MedusaResponse`:
```ts
import type { NextFunction, Request, Response } from "express"
import type { Customer, User } from "../models"
import type { MedusaContainer } from "./global"
export interface MedusaRequest<T = unknown> extends Request {
user?: (User | Customer) & { customer_id?: string; userId?: string }
scope: MedusaContainer
}
export type MedusaResponse<T = unknown> = Response
export type MedusaNextFunction = NextFunction
export type MedusaRequestHandler = (
req: MedusaRequest,
res: MedusaResponse,
next: MedusaNextFunction
) => Promise<void> | void
```
You can then add type arguments to the routes in `packages/medusa/src/api-v2/admin/campaigns/[id]/route.ts`. For example:
```ts
import {
deleteCampaignsWorkflow,
updateCampaignsWorkflow,
} from "@medusajs/core-flows"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
import { CampaignDTO, IPromotionModuleService } from "@medusajs/types"
import { MedusaRequest, MedusaResponse } from "../../../../types/routing"
interface ResponseType {
campaign: CampaignDTO
}
export const GET = async (
req: MedusaRequest,
res: MedusaResponse<ResponseType>
) => {
const promotionModuleService: IPromotionModuleService = req.scope.resolve(
ModuleRegistrationName.PROMOTION
)
const campaign = await promotionModuleService.retrieveCampaign(
req.params.id,
{
select: req.retrieveConfig.select,
relations: req.retrieveConfig.relations,
}
)
res.status(200).json({ campaign })
}
export const POST = async (
req: MedusaRequest<{
id: string
}>,
res: MedusaResponse<ResponseType>
) => {
const updateCampaigns = updateCampaignsWorkflow(req.scope)
const campaignsData = [
{
id: req.params.id,
...(req.validatedBody || {}),
},
]
const { result, errors } = await updateCampaigns.run({
input: { campaignsData },
throwOnError: false,
})
if (Array.isArray(errors) && errors[0]) {
throw errors[0].error
}
res.status(200).json({ campaign: result[0] })
}
export const DELETE = async (
req: MedusaRequest,
res: MedusaResponse<{
id: string
object: string
deleted: boolean
}>
) => {
const id = req.params.id
const manager = req.scope.resolve("manager")
const deleteCampaigns = deleteCampaignsWorkflow(req.scope)
const { errors } = await deleteCampaigns.run({
input: { ids: [id] },
context: { manager },
throwOnError: false,
})
if (Array.isArray(errors) && errors[0]) {
throw errors[0].error
}
res.status(200).json({
id,
object: "campaign",
deleted: true,
})
}
```
### Generate OAS
- Install dependencies in the `docs-util` directory
- Run the following command in the `docs-util/packages/docblock-generator` directory:
```bash
yarn dev run "../../../packages/medusa/src/api-v2/admin/campaigns/[id]/route.ts"
```
This will generate the OAS operation and schemas and necessary and update the base YAML to include the new tags.
### Generate OAS with Examples
By default, the tool will only generate cURL examples for OAS operations. To generate templated JS Client and (placeholder) Medusa React examples, add the `--generate-examples` option to the command:
```bash
yarn dev run "../../../packages/medusa/src/api-v2/admin/campaigns/[id]/route.ts" --generate-examples
```
> Note: the command will update the existing OAS you generated in the previous test.
### Testing Updates
To test updating OAS, you can try updating request/response types, then running the command, and the associated OAS/schemas will be updated.
### Clean OAS
The `clean:oas` command will remove any unused operation, tags, or schemas. To test it out you can try:
- Remove an API Route => this removes its associated operation and schemas (if not referenced anywhere else).
- Remove all references to a schema => this removes the schema.
- Remove all operations in `docs-util/oas-output/operations` associated with a tag => this removes the tag from the base YAML.
```bash
yarn dev clean:oas
```
> Note: when running this command, existing tags in the base YAML (such as Products) will be removed since there are no operations using it. As it's running on the base YAML under `base-v2`, this doesn't affect base YAML used for the API reference.
### Medusa Oas CLI
- Install and build dependencies in the root of the monorepo
- Run the following command to generate reference OAS for v2 API Routes (must have generated OAS previously using the docblock generator tool):
```bash
yarn openapi:generate --v2
```
- This wipes out existing OAS in `www/apps/api-reference/specs` and replaces them with the new ones. At this point, you can view the new API routes in the API reference by running the `yarn dev` command in `www/apps/api-reference` (although not necessary for testing here).
- Run the command again without the `--v2` option:
```bash
yarn openapi:generate
```
The specs in `www/apps/api-reference/specs` are reverted back to the old routes.
- Fix GitHub action to run on push and check if the commit message is "chore: Release". Only then are TSDocs generated and a PR is opened.
- Add an option to pass to the `run:release` method of the docblock generator a release tag. This is helpful in cases when the GitHub action fails for any reason.
- Add scripts that checks the message of a commit.
This PR changes the original process of generating docblocks through actions. The process now is:
1. When a PR is merged for the branch `changeset-release/develop`, the docblock generator tool us used to generate docblocks for the changed files. The changed files are determined by retrieving all comments since the last release and the files in each of those commits.
2. If there are changes after using the docblock generator tool, a PR is opened in the branch `chore/generate-tsdocs`.
3. Once the `chore/generate-tsdocs` is merged, it triggers an action that generates the references for the docs. This changes the previous behaviour of generating references on a new release.
Both actions (that runs the docblock generator tool and that generates references for the docs) can also be triggered manually.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## What
Updates `@redocly/cli` to v1.7. This resolves the bug of TypeScript and tsx code samples in the OAS being generated as undefined files (see files under `www/apps/api-reference/specs/admin/code_samples/tsx` and `www/apps/api-reference/specs/store/code_samples/tsx`
I avoided re-generating OAS so that this PR doesn't have a huge diff. When the next release is out, an automated PR will be opened to update the OAS files, replacing the undefined files with `.tsx` files.
### Other Changes
- Small fixes to `medusa-oas-cli` README for clarity
- Added anchor links to items in parameter components
- Added sectionTitle prop in markdown theme
Note: Due to the second point, the change requires generating references to see the anchor links, which would result in a big diff in this PR. Instead, next time the references are generated for a release, this feature will available for use.
- Add a new deployment overview page giving a general overview of how a Medusa project is deployed
- Add a new section in all backend deployment guides related to the Medusa admin.
- Add a general deployment guide for the medusa admin.
- Add a general deployment guide for the Next.js starter
- Move the admin plugin's options to the Admin Configuration documentation.
- Add a section on how to change the backend URL for both development and production.
- Fix the troubleshooting section related to port forwarding.
- General fixes.
Shahed NasserandGitHub
