@medusajs/http-types-generator 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +46 -0
  2. package/README.md +80 -94
  3. package/package.json +6 -2
package/AGENTS.md ADDED
@@ -0,0 +1,46 @@
1
+ # @medusajs/http-types-generator
2
+
3
+ The `medusa-http-types` CLI. It generates TypeScript HTTP interfaces from the Zod schemas exported by API route `validators.ts` files, and validates that existing interfaces still match those schemas. In this repo it keeps `packages/core/types/src/http` in sync with `packages/medusa/src/api/{admin,store}/*/validators.ts`.
4
+
5
+ ## Using this package
6
+
7
+ From the repo root (the `dist` build must exist; the scripts run `node dist/index.js`):
8
+
9
+ ```bash
10
+ yarn generate:http-types --domain products --dry-run
11
+ yarn generate:http-types --domain products
12
+ yarn validate:http-types
13
+ yarn validate:http-types --domain products --verbose
14
+ ```
15
+
16
+ - `generate`: `--area <admin|store|all>`, `--domain <routeDir>`, `--dry-run`, `--force`, `--verbose`.
17
+ - `validate`: `--area`, `--domain`, `--changed-files <comma-separated>`, `--lenient`, `--ci` (exit 1 on failure), `--verbose`.
18
+ - Config comes from the nearest `http-types.config.json` found by walking up from the cwd; its directory becomes the project root. The repo's root config points output to `packages/core/types/src/http` and imports `FindParams`/`BaseFilterable` from local `packages/core/types` paths.
19
+ - Only exports whose name starts with a `publicPrefixes` entry (default `Admin`, `Store`) are processed. Names matching `Params`/`Filters` go to `queries.ts`; everything else goes to `payloads.ts`.
20
+
21
+ ## Architecture
22
+
23
+ - `src/commands/generate.ts`, `src/commands/validate.ts`: commander subcommands.
24
+ - `src/config/index.ts`: `Config.load()` / `Config.get()` singleton. Defaults are deep-merged with the user config.
25
+ - `src/core/`: `program-factory` (TS program from the configured tsconfig), `schema-extractor` (Zod exports), `type-resolver` + `type-emitter` (TS types to interface text), `import-tracker`, `compatibility-checker` (validate).
26
+ - `src/mapping/path-mapper.ts`: route dir to domain. It singularizes the last hyphen segment (`sales-channels` becomes `sales-channel`); `ENTITY_NAME_OVERRIDES` handles legacy exceptions (e.g. `addresses` maps to `customer`). Output path: `<outputBase>/<domain>/<area>/{payloads,queries}.ts`.
27
+ - `src/mapping/name-classifier.ts`, `name-registry.ts`: output file and interface naming.
28
+ - `src/utils/file-merger.ts`: new file is created; existing file is merged (only interfaces not already declared are added) unless `--force` overwrites it.
29
+ - `src/utils/index-manager.ts`: updates `{domain}/{area}/index.ts`, `{domain}/index.ts` and `<outputBase>/index.ts` barrels.
30
+
31
+ ## Development
32
+
33
+ ```bash
34
+ yarn build # tsc --build (required before the generate/validate scripts)
35
+ yarn test # jest --bail --forceExit over src
36
+ ../../../node_modules/.bin/jest src/__tests__/path-mapper.spec.ts
37
+ ```
38
+
39
+ Tests are in `src/__tests__/`; `src/__tests__/utils/` holds helpers and is excluded from test matching.
40
+
41
+ ## Gotchas
42
+
43
+ - CI (`.github/workflows/validate-http-types.yml`) runs `validate --ci` on PRs that touch `packages/medusa/src/api/**/validators.ts`, `packages/core/types/src/http/**`, or this package. When you change a validator, update or regenerate the matching HTTP type, or CI fails.
44
+ - Without `--force`, `generate` never updates an interface that already exists. To pick up schema changes in existing types, edit them by hand or regenerate with `--force` and review the diff.
45
+ - Don't add entries to `ENTITY_NAME_OVERRIDES` for new routes. Name the route directory so automatic singularization yields the right domain.
46
+ - An invalid `validatorPathPattern` regex throws at config load. An unparsable config file logs a warning and silently falls back to defaults.
package/README.md CHANGED
@@ -1,83 +1,104 @@
1
- # @medusajs/http-types-generator
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/http-types-generator
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ `@medusajs/http-types-generator` is a CLI that generates TypeScript HTTP request types (payload and query interfaces) from the Zod schemas in API route `validators.ts` files, and validates that existing HTTP types still match those schemas. The Medusa monorepo uses it to keep `@medusajs/types` HTTP types in sync with the `@medusajs/medusa` API validators; you can also run it in your own project to type custom `/admin` and `/store` routes.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/http-types-generator` |
44
+ | Type | Internal tooling |
45
+ | Binary | `medusa-http-types` |
46
+
47
+ ## Installation
2
48
 
3
- CLI tool that generates and validates TypeScript HTTP types from Zod validator schemas.
4
-
5
- ## How it works
6
-
7
- The tool scans validator files, extracts exported Zod schemas, resolves their TypeScript types, and emits `interface` declarations into output files. It can also check whether existing HTTP type files are structurally compatible with their corresponding Zod schemas.
8
-
9
- ---
49
+ ```bash
50
+ npm install --save-dev @medusajs/http-types-generator
51
+ ```
10
52
 
11
- ## Usage in the Medusa monorepo
53
+ ## Usage
12
54
 
13
- Run from the repo root using the workspace scripts:
55
+ In the Medusa monorepo, run the root workspace scripts. The root `http-types.config.json` already points the tool at the monorepo paths:
14
56
 
15
57
  ```bash
16
- # Generate types for a domain
17
58
  yarn generate:http-types --domain products --dry-run
18
59
  yarn generate:http-types --domain products
19
-
20
- # Validate all types
21
- yarn validate:http-types
22
-
23
- # Validate a single domain
24
60
  yarn validate:http-types --domain products --verbose
25
61
  ```
26
62
 
27
- The repo root's `http-types.config.json` configures the Medusa-specific paths automatically — no additional setup is needed.
63
+ In your own project:
28
64
 
29
- ---
65
+ ```bash
66
+ npx medusa-http-types generate --dry-run
67
+ npx medusa-http-types validate --ci
68
+ ```
69
+
70
+ Only schemas exported from a `validators.ts` file matching `validatorPathPattern` whose names start with a `publicPrefixes` entry are processed. Each schema becomes an interface in `<outputBase>/<domain>/<area>/queries.ts` (names ending in `Params` or `Filters`, and `AdminGet*` / `StoreGet*`) or `payloads.ts` (everything else, such as `Create*` and `Update*` bodies), where `<domain>` is the singular of the route directory (e.g. `products` -> `product`).
30
71
 
31
72
  ## Commands
32
73
 
33
74
  ### `generate`
34
75
 
35
- Generates TypeScript interface files from Zod schemas.
36
-
37
- ```bash
38
- yarn generate:http-types [options]
39
- ```
76
+ Generates TypeScript interfaces from Zod schemas. Without `--force`, existing files are kept and only missing interfaces are added.
40
77
 
41
78
  | Option | Description | Default |
42
- |---|---|---|
43
- | `--area <area>` | Area to process. Must match a key in `validatorGlobs` (`store` or `admin` for monorepo), or `all` for every area. | `all` |
44
- | `--domain <domain>` | Limit to a specific domain (route directory name). | — |
79
+ | --- | --- | --- |
80
+ | `--area <area>` | Area to process: a key of `validatorGlobs` (`admin`, `store`) or `all`. | `all` |
81
+ | `--domain <domain>` | Limit to one route directory (e.g. `products`). | - |
45
82
  | `--dry-run` | Print what would be generated without writing files. | `false` |
46
- | `--force` | Overwrite existing files instead of merging. | `false` |
83
+ | `--force` | Overwrite existing files instead of merging into them. | `false` |
47
84
  | `--verbose` | Print each processed schema. | `false` |
48
85
 
49
86
  ### `validate`
50
87
 
51
88
  Checks that existing HTTP types are structurally compatible with their Zod schemas.
52
89
 
53
- ```bash
54
- yarn validate:http-types [options]
55
- ```
56
-
57
90
  | Option | Description | Default |
58
- |---|---|---|
91
+ | --- | --- | --- |
59
92
  | `--area <area>` | Area to validate. | `all` |
60
- | `--domain <domain>` | Limit to a specific domain. | — |
61
- | `--changed-files <paths>` | Comma-separated list of changed validator files (CI optimisation). | — |
93
+ | `--domain <domain>` | Limit to one route directory. | - |
94
+ | `--changed-files <paths>` | Comma-separated list of changed validator files to check. | - |
62
95
  | `--lenient` | Treat `T \| null \| undefined` as compatible with `T \| undefined`. | `false` |
63
- | `--ci` | Exit with code 1 if any failures are found. | `false` |
96
+ | `--ci` | Exit with code 1 if any check fails. | `false` |
64
97
  | `--verbose` | Show passing types in addition to failures. | `false` |
65
98
 
66
- ---
67
-
68
- ## General usage
69
-
70
- ### Installation
99
+ ## Configuration
71
100
 
72
- ```bash
73
- npm install --save-dev @medusajs/http-types-generator
74
- # or run without installing:
75
- npx @medusajs/http-types-generator generate
76
- ```
77
-
78
- ### Configuration
79
-
80
- Place an `http-types.config.json` file in your project root. All fields are optional and are deep-merged over the defaults.
101
+ Add an optional `http-types.config.json`. The CLI uses the nearest one found by searching upward from the working directory, treats its directory as the project root, and deep-merges it over the defaults.
81
102
 
82
103
  ```json
83
104
  {
@@ -85,51 +106,16 @@ Place an `http-types.config.json` file in your project root. All fields are opti
85
106
  "admin": "src/api/admin/*/validators.ts",
86
107
  "store": "src/api/store/*/validators.ts"
87
108
  },
88
- "outputBase": "src/types/http",
89
- "tsconfig": "tsconfig.json",
90
- "importSources": {
91
- "commonRequest": "@medusajs/framework/types",
92
- "dal": "@medusajs/framework/types"
93
- },
94
- "validatorPathPattern": "/api/([^/]+)/([^/]+)/validators\\.ts$",
95
- "publicPrefixes": ["Admin", "Store"]
109
+ "outputBase": "src/types/http"
96
110
  }
97
111
  ```
98
112
 
99
- | Field | Description | Default |
100
- |---|---|---|
101
- | `validatorGlobs` | Glob patterns (relative to project root) keyed by area name. | `{ admin: "**/api/admin/*/validators.ts", store: "**/api/store/*/validators.ts" }` |
102
- | `outputBase` | Root directory for generated files, relative to project root. | `"src/types/http"` |
103
- | `tsconfig` | tsconfig filename at the project root used when creating the TypeScript program. | `"tsconfig.json"` |
104
- | `importSources.commonRequest` | Module that exports `FindParams` and `SelectParams`. | `"@medusajs/framework/types"` |
105
- | `importSources.dal` | Module that exports `BaseFilterable` and `OperatorMap`. | `"@medusajs/framework/types"` |
106
- | `validatorPathPattern` | Regex (no surrounding `/`) with two capture groups: `(area, routeDir)`. | `"/api/([^/]+)/([^/]+)/validators\\.ts$"` |
107
- | `publicPrefixes` | Only schemas whose name starts with one of these prefixes are processed. | `["Admin", "Store"]` |
108
-
109
- The config file is found by searching upward from the working directory, so it works whether the CLI is invoked from the project root or a subdirectory.
110
-
111
- ### Validator file conventions
112
-
113
- Schemas must be exported from a `validators.ts` file whose path matches `validatorPathPattern`. The pattern must have two capture groups: area and route directory.
114
-
115
- ```
116
- src/api/admin/products/validators.ts → area=admin, routeDir=products
117
- ```
118
-
119
- Export names must start with one of the `publicPrefixes`. The suffix determines the output file:
120
-
121
- - Matches `Params`, `Filters` → `queries.ts`
122
- - Matches `Create`, `Update`, `Batch`, etc. → `payloads.ts`
123
- - Everything else defaults to `payloads.ts`
124
-
125
- ### Running with npx
126
-
127
- ```bash
128
- # Generate
129
- npx @medusajs/http-types-generator generate --dry-run
130
- npx @medusajs/http-types-generator generate --domain products
131
-
132
- # Validate
133
- npx @medusajs/http-types-generator validate
134
- npx @medusajs/http-types-generator validate --ci
135
- ```
113
+ | Option | Type | Description | Default |
114
+ | --- | --- | --- | --- |
115
+ | `validatorGlobs` | `Record<string, string>` | Validator file globs keyed by area, relative to the project root. | `{ "admin": "**/api/admin/*/validators.ts", "store": "**/api/store/*/validators.ts" }` |
116
+ | `outputBase` | `string` | Output directory for generated files, relative to the project root. | `"src/types/http"` |
117
+ | `tsconfig` | `string` | tsconfig file used to resolve the schema types. | `"tsconfig.json"` |
118
+ | `importSources.commonRequest` | `string` | Module that exports `FindParams` and `SelectParams`. | `"@medusajs/framework/types"` |
119
+ | `importSources.dal` | `string` | Module that exports `BaseFilterable` and `OperatorMap`. | `"@medusajs/framework/types"` |
120
+ | `validatorPathPattern` | `string` | Regex (no surrounding `/`) with two capture groups: area and route directory. | `"/api/([^/]+)/([^/]+)/validators\\.ts$"` |
121
+ | `publicPrefixes` | `string[]` | Only schemas whose export name starts with one of these are processed. | `["Admin", "Store"]` |
package/package.json CHANGED
@@ -1,14 +1,18 @@
1
1
  {
2
2
  "name": "@medusajs/http-types-generator",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Generate and validate HTTP TypeScript types",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
7
7
  "medusa-http-types": "dist/index.js"
8
8
  },
9
9
  "files": [
10
- "dist"
10
+ "dist",
11
+ "AGENTS.md"
11
12
  ],
13
+ "llms": "https://docs.medusajs.com/llms.txt",
14
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
15
+ "mcpServer": "https://docs.medusajs.com/mcp",
12
16
  "repository": {
13
17
  "type": "git",
14
18
  "url": "git+https://github.com/medusajs/medusa.git",