@passelin/mock-bff 0.4.2

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 (18) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +185 -0
  3. package/admin/dist/assets/bff_candy_heart-tUzGTaBH.svg +1 -0
  4. package/admin/dist/assets/index-DqEQC4bI.js +268 -0
  5. package/admin/dist/assets/index-QJ-IaVhl.js +256 -0
  6. package/admin/dist/assets/index-tkgDpq0U.css +1 -0
  7. package/admin/dist/index.html +18 -0
  8. package/dist/ai.js +289 -0
  9. package/dist/app.js +869 -0
  10. package/dist/cli.js +94 -0
  11. package/dist/har.js +106 -0
  12. package/dist/matcher.js +41 -0
  13. package/dist/openapi.js +116 -0
  14. package/dist/server.js +16 -0
  15. package/dist/storage.js +257 -0
  16. package/dist/types.js +1 -0
  17. package/dist/utils.js +62 -0
  18. package/package.json +81 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,185 @@
1
+ # mock-bff
2
+
3
+ <img src="./admin/src/assets/bff_candy_heart.svg" alt="Mock BFF logo" width="180" />
4
+
5
+ Mock BFF server for UI development. Run frontend apps against realistic HTTP API responses without standing up backend environments.
6
+
7
+ Feed it a HAR recording or an OpenAPI contract, and it replays stored mocks. For requests with no match, it can generate a realistic response using an AI provider.
8
+
9
+ ## Features
10
+
11
+ - Replay HTTP API responses from HAR recordings
12
+ - Filesystem-based mock storage (commit-friendly)
13
+ - Admin UI at `/-/admin` for managing endpoints and variants
14
+ - OpenAPI validation (assist and strict modes)
15
+ - AI fallback generation via OpenAI, Anthropic, or Ollama
16
+ - Live request/miss observability via SSE
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ npx @passelin/mock-bff
22
+ ```
23
+
24
+ Or install globally:
25
+
26
+ ```bash
27
+ npm install -g @passelin/mock-bff
28
+ mock-bff --help
29
+ ```
30
+
31
+ ## Quick start
32
+
33
+ ```bash
34
+ # Start with no AI (pure HAR replay)
35
+ mock-bff --provider none
36
+
37
+ # Start with OpenAI fallback
38
+ export OPENAI_API_KEY=your_key
39
+ mock-bff --provider openai --model gpt-4o
40
+
41
+ # Start on a custom port
42
+ mock-bff --port 3001 --provider none
43
+ ```
44
+
45
+ Then open `http://localhost:8787/-/admin` to import a HAR file and manage mocks.
46
+
47
+ ## CLI options
48
+
49
+ ```
50
+ -p, --port <number> Server port (default: 8787)
51
+ -H, --host <host> Server host (default: 0.0.0.0)
52
+ -r, --root <path> Project root directory (default: cwd)
53
+ -a, --app-name <name> App name label (default: local-app)
54
+ --provider <name> AI provider: openai|anthropic|ollama|none (default: openai)
55
+ --model <id> AI model id (provider-specific)
56
+ --openai-base-url <url> OpenAI-compatible base URL override
57
+ --anthropic-base-url <url> Anthropic base URL override
58
+ --ollama-base-url <url> Ollama base URL (default: http://127.0.0.1:11434)
59
+ -h, --help Show help
60
+ ```
61
+
62
+ ## AI provider setup
63
+
64
+ ### OpenAI
65
+
66
+ ```bash
67
+ export OPENAI_API_KEY=your_key
68
+ mock-bff --provider openai --model gpt-4o
69
+ ```
70
+
71
+ ### Anthropic
72
+
73
+ ```bash
74
+ export ANTHROPIC_API_KEY=your_key
75
+ mock-bff --provider anthropic --model claude-3-5-sonnet-latest
76
+ ```
77
+
78
+ ### Ollama (local)
79
+
80
+ ```bash
81
+ # default base URL is http://127.0.0.1:11434
82
+ mock-bff --provider ollama --model llama3.1:8b
83
+
84
+ # override base URL
85
+ mock-bff --provider ollama --model llama3.1:8b --ollama-base-url http://localhost:11434
86
+ ```
87
+
88
+ ### Disable AI generation
89
+
90
+ ```bash
91
+ mock-bff --provider none
92
+ ```
93
+
94
+ ## Environment variables
95
+
96
+ | Variable | Description |
97
+ |---|---|
98
+ | `OPENAI_API_KEY` | Required when using `--provider openai` |
99
+ | `ANTHROPIC_API_KEY` | Required when using `--provider anthropic` |
100
+ | `OPENAI_BASE_URL` | Optional OpenAI-compatible base URL override |
101
+ | `ANTHROPIC_BASE_URL` | Optional Anthropic base URL override |
102
+ | `OLLAMA_BASE_URL` | Optional Ollama base URL override |
103
+ | `MOCK_MAX_UPLOAD_BYTES` | Upload size limit in bytes (default: 250MB) |
104
+ | `MOCK_MAX_REQUEST_LOGS` | Max request log entries kept in memory (default: 500) |
105
+
106
+ ## Admin UI
107
+
108
+ Open `http://localhost:8787/-/admin` to:
109
+
110
+ - Import HAR files and OpenAPI contracts
111
+ - Browse and search endpoints
112
+ - Review and edit response variants
113
+ - Monitor live requests and misses
114
+ - Configure AI provider and prompt template
115
+
116
+ ## Mock storage
117
+
118
+ Mocks are stored as JSON files under a `mocks/` directory in the project root (the directory where you run `mock-bff`). This makes them easy to commit alongside your frontend code.
119
+
120
+ ```
121
+ mocks/
122
+ ├── _meta/
123
+ │ ├── app.config.json # Server configuration
124
+ │ ├── index.json # Endpoint/variant index
125
+ │ └── context.md # Optional AI context hints
126
+ ├── GET/
127
+ │ └── api__orders/
128
+ │ └── default.json
129
+ └── POST/
130
+ └── api__users/
131
+ └── q_abc123__b_def456.json
132
+ ```
133
+
134
+ ## Config highlights
135
+
136
+ Configuration is managed via the Admin UI Settings page or by editing `mocks/_meta/app.config.json` directly.
137
+
138
+ - `har.ignorePatterns`: glob-like path patterns to skip during HAR import (e.g. `/.well-known/*`)
139
+ - `har.onlyApiCalls`: skip non-API requests (assets, fonts, etc.) during import
140
+ - `openApiMode`: `off` | `assist` | `strict` — controls OpenAPI validation behavior
141
+ - `aiPromptTemplate`: customize the AI generation prompt using placeholders:
142
+ - `{{method}}`, `{{path}}`, `{{query_json}}`, `{{body_json}}`, `{{headers_json}}`
143
+ - `{{context}}`, `{{similar_examples_json}}`, `{{datetime_iso}}`
144
+
145
+ ## API reference
146
+
147
+ | Method | Path | Description |
148
+ |---|---|---|
149
+ | `GET` | `/-/api/health` | Server health and version |
150
+ | `GET` | `/-/api/config` | Read configuration |
151
+ | `PATCH` | `/-/api/config` | Update configuration |
152
+ | `GET` | `/-/api/providers` | List available AI providers and models |
153
+ | `POST` | `/-/api/har` | Import HAR file |
154
+ | `GET` | `/-/api/openapi` | Get current OpenAPI spec |
155
+ | `POST` | `/-/api/openapi` | Upload OpenAPI spec |
156
+ | `DELETE` | `/-/api/openapi` | Remove OpenAPI spec |
157
+ | `GET` | `/-/api/endpoints` | List all endpoints |
158
+ | `DELETE` | `/-/api/endpoint` | Delete a single endpoint (`?method=GET&path=/api/x`) |
159
+ | `DELETE` | `/-/api/endpoints` | Delete all endpoints |
160
+ | `GET` | `/-/api/variants` | List variants for an endpoint |
161
+ | `GET` | `/-/api/variant` | Get a single variant |
162
+ | `PUT` | `/-/api/variant` | Create or update a variant |
163
+ | `DELETE` | `/-/api/variant` | Delete a variant |
164
+ | `GET` | `/-/api/requests` | Request log |
165
+ | `DELETE` | `/-/api/requests` | Clear request log |
166
+ | `GET` | `/-/api/misses` | Unmatched request log |
167
+ | `DELETE` | `/-/api/misses` | Clear misses log |
168
+ | `GET` | `/-/api/context` | Get AI context |
169
+ | `PUT` | `/-/api/context` | Update AI context |
170
+ | `GET` | `/-/api/events` | SSE stream for live UI updates |
171
+
172
+ ## Development
173
+
174
+ ```bash
175
+ git clone https://github.com/passelin/mock-bff.git
176
+ cd mock-bff
177
+ npm install
178
+ npm run build:admin
179
+ npm test
180
+ npm run dev
181
+ ```
182
+
183
+ ## License
184
+
185
+ MIT
package/admin/dist/assets/bff_candy_heart-tUzGTaBH.svg ADDED
@@ -0,0 +1 @@
1
+ <svg clip-rule="evenodd" fill-rule="evenodd" stroke-linejoin="round" stroke-miterlimit="2" viewBox="0 0 350 350" xmlns="http://www.w3.org/2000/svg"><g fill-rule="nonzero"><path d="m250 390c-90-50-160-100-160-180 0-55 40-95 90-95 30 0 55 15 70 35 15-20 40-35 70-35 50 0 90 40 90 95 0 80-70 130-160 180z" fill="#f5aecb" transform="translate(-75 -75)"/><g fill="#f1687c" transform="matrix(.475014 .0358978 -.0358978 .475014 -55.6153 -68.70067)"><path d="m443.017 406.627c3.989 17.883-4.666 30.221-18.623 41.557 4.387 1.212 7.108 1.963 10.217 2.725 18.334 1.675 32.858 18.069 33.567 35.942.478 12.037-2.072 22.843-10.868 30.805-6.268 5.673-13.887 10.377-21.667 13.752-17.545 7.609-36.234 11.364-55.203 13.605-2.951.349-5.906.669-8.861.985-15.085 1.613-20.501-5.035-24.344-17.549-8.443-27.493-15.762-55.337-23.25-83.116-2.489-9.233-3.688-18.814-6.203-28.038-3.084-11.315 2.994-21.45 13.789-25.361 11.793-4.272 23.906-7.822 36.099-10.781 8.778-2.131 17.939-3.976 26.889-3.806 13.134.25 26.679.849 37.494 10.304 5.698 4.981 8.982 11.397 10.964 18.976m-38.659 102.405c3.406-1.698 6.885-3.266 10.204-5.119 13.105-7.314 9.565-22.151.136-28.027-10.776-6.714-21.907-4.741-32.847-.579-1.316.501-2.592 3.891-2.219 5.572 1.821 8.215 4.226 16.3 6.389 24.441 1.755 6.605 3.214 7.491 9.887 5.842 2.563-.633 5.121-1.292 8.45-2.13m-25.638-61.834c7.031-1.564 13.658-3.933 18.849-9.26 8.702-8.931 5.091-22.523-6.887-25.86-7.619-2.123-15.066-1.123-22.408 1.316-5.372 1.785-6.182 3.489-4.662 8.882 1.837 6.511 3.621 13.038 5.359 19.576 1.419 5.338 3.173 6.484 9.749 5.346z"/><path d="m608.89 365.343c6.389-6.847 14.561-7.859 22.913-8.341 11.717-.675 23.446-2.011 35.151-1.829 14.345.222 28.745 1.123 42.98 2.876 9.464 1.165 12.961 7.121 12.048 16.643-.937 9.763-6.614 15.243-16.113 15.288-15.301.073-30.603.054-45.904-.001-4.402-.016-7.442 1.444-7.908 6.641-.001 4.378-.18 8.382-.021 12.372.305 7.632 4.189 11.54 11.759 11.994 11.737.703 23.476 1.349 35.214 2.016 8.413.479 13.356 7.625 12.588 16.114-1.211 13.379-9.072 15.642-19.283 15.724-10.066.081-20.151-1.037-30.211-1.84-5.874-.468-8.314 1.382-8.054 7.403.486 11.246 1.459 22.473 1.819 33.721.136 4.24-.193 8.754-1.581 12.695-.981 2.782-3.676 5.637-6.35 7.018-7.508 3.878-15.801 3.179-23.681 1.553-5.51-1.138-9.175-5.567-10.165-11.226-1.334-7.631-2.355-15.34-3.036-23.057-1.496-16.964-2.709-33.953-4.004-50.934-.403-5.282-.817-10.567-1.016-15.858-.419-11.115-1.125-22.245-.845-33.347.129-5.125 2.296-10.199 3.7-15.625z"/><path d="m567.247 392.956c-.704-.313-1.172-.618-1.943-.898-13.474 1.023-26.649 1.951-39.809 3.065-3.705.314-6.159 2.045-5.532 6.47.808 5.706 1.141 11.485 2.07 17.168.778 4.756 4.272 7.271 8.813 7.135 9.405-.283 18.788-1.211 28.189-1.707 4.477-.237 9.019-.506 13.451-.02 5.796.634 10.231 6.141 10.512 12.099.145 3.098.286 6.196.712 9.514-.306 1.66-.896 3.099-1.649 4.835-9.453 8.068-20.613 7.392-31.681 7.436-6.108.025-12.214.583-18.321.913-4.189.227-5.04 2.46-4.496 6.378 1.971 14.195 3.66 28.429 5.431 42.651.654 5.248-2.161 9.027-6.544 10.519-9.016 3.072-18.349 4.218-28.017.515-5.131-5.22-7.419-11.373-8.547-18.28-3.767-23.081-8.114-46.069-11.693-69.178-2.244-14.486-3.51-29.124-5.245-44.133-.002-2.27 0-4.103.058-5.935.219-6.89 3.498-11.882 10.267-13.575 10.552-2.639 21.187-5.389 31.955-6.622 17.9-2.048 35.924-3.085 53.916-4.221 6.182-.391 12.419 3.981 14.367 9.004 3.009 7.756 2.123 16.825-2.677 20.368-2.837 2.095-6.513 3.056-9.816 4.515-.983.434-1.984.829-3.02 1.621-.043.379-.515.372-.751.363z"/></g></g></svg>