@apicircle/mock-server-core 1.0.1 → 1.0.3

package/LICENSE

@@ -1,110 +1,110 @@
-API Circle Studio License
-Custom Source-Available License, v1.0
-
-Copyright (c) 2026 Deva Prakash ("Licensor")
-
-The source code in this repository ("the Software") is made available for
-the purposes of transparency, security review, contribution, and personal
-evaluation. This is NOT an open-source license as defined by the Open
-Source Initiative.
-
-0. Definitions
-
-   "Commercial Use" means any use of the Software that is intended for
-   or directed toward commercial advantage or monetary compensation,
-   whether direct or indirect, including without limitation:
-
-   (a) using the Software to build, test, develop, deploy, or operate
-       any product, service, application, or system that is sold,
-       licensed, hosted, distributed, or otherwise made available to
-       any third party for a fee or other consideration;
-   (b) using the Software in the course of paid employment, paid
-       consulting, paid contracting, freelance work, or any other
-       revenue-generating activity, regardless of whether the Software
-       itself is sold or transferred;
-   (c) using the Software internally within a for-profit organization
-       beyond the Evaluation Period defined below;
-   (d) integrating the Software, or any portion of it, into any tool,
-       pipeline, automation, or workflow that supports the commercial
-       operations of any business;
-   (e) using the Software to provide a hosted, managed, or embedded
-       service of any kind to a third party, whether free or paid.
-
-   "Non-Commercial Use" means any use that is not Commercial Use,
-   including personal hobby projects, individual learning, academic
-   research, classroom instruction, and good-faith contribution to
-   this repository.
-
-   "Evaluation Period" means a single, continuous period of up to
-   thirty (30) days during which a for-profit organization may
-   internally evaluate the Software at no charge. After the Evaluation
-   Period expires, any further use of the Software by that organization
-   constitutes Commercial Use and requires a separate commercial
-   license from the Licensor.
-
-1. Permitted Use
-
-   You may, without charge:
-
-   (a) view, read, and study the source code of the Software;
-   (b) run the Software, in source or compiled form, for your own
-       Non-Commercial Use, or for Commercial Use solely within the
-       Evaluation Period;
-   (c) submit improvements to the Software back to this repository via
-       pull request, subject to Section 3 (Contributions).
-
-2. Prohibited Use
-
-   Without prior written permission from the Licensor, you may NOT:
-
-   (a) make any Commercial Use of the Software, in whole or in part,
-       except during the Evaluation Period as defined in Section 0;
-   (b) redistribute the Software, in source or compiled form, whether
-       modified or unmodified, to any third party;
-   (c) sublicense, sell, rent, lease, or otherwise transfer the
-       Software or any rights granted herein;
-   (d) remove, obscure, or alter any copyright, trademark, attribution,
-       or license notice contained in the Software;
-   (e) use the names "API Circle", "API Circle Studio", or any related
-       logos or trademarks, except as required for accurate attribution.
-
-3. Contributions
-
-   By submitting any contribution (including but not limited to code,
-   documentation, or assets) to this repository, you grant the Licensor
-   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
-   license to use, modify, distribute, and relicense your contribution
-   under any terms, including the terms of this license or any future
-   version thereof.
-
-4. No Trademark License
-
-   This license does not grant permission to use the trade names,
-   trademarks, service marks, or product names of the Licensor, except
-   as required for reasonable and customary use in describing the
-   origin of the Software.
-
-5. Termination
-
-   The rights granted in Section 1 terminate automatically if you
-   breach any term of this license. Upon termination, you must cease
-   all use of the Software and destroy all copies in your possession.
-
-6. Disclaimer of Warranty
-
-   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
-   NON-INFRINGEMENT.
-
-7. Limitation of Liability
-
-   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
-   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
-   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
-   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-8. Commercial Licensing
-
-   For commercial licensing, redistribution, or any use not permitted
-   under Section 1, contact: apicircle365@gmail.com
+API Circle Studio License
+Custom Source-Available License, v1.0
+
+Copyright (c) 2026 Deva Prakash ("Licensor")
+
+The source code in this repository ("the Software") is made available for
+the purposes of transparency, security review, contribution, and personal
+evaluation. This is NOT an open-source license as defined by the Open
+Source Initiative.
+
+0. Definitions
+
+   "Commercial Use" means any use of the Software that is intended for
+   or directed toward commercial advantage or monetary compensation,
+   whether direct or indirect, including without limitation:
+
+   (a) using the Software to build, test, develop, deploy, or operate
+       any product, service, application, or system that is sold,
+       licensed, hosted, distributed, or otherwise made available to
+       any third party for a fee or other consideration;
+   (b) using the Software in the course of paid employment, paid
+       consulting, paid contracting, freelance work, or any other
+       revenue-generating activity, regardless of whether the Software
+       itself is sold or transferred;
+   (c) using the Software internally within a for-profit organization
+       beyond the Evaluation Period defined below;
+   (d) integrating the Software, or any portion of it, into any tool,
+       pipeline, automation, or workflow that supports the commercial
+       operations of any business;
+   (e) using the Software to provide a hosted, managed, or embedded
+       service of any kind to a third party, whether free or paid.
+
+   "Non-Commercial Use" means any use that is not Commercial Use,
+   including personal hobby projects, individual learning, academic
+   research, classroom instruction, and good-faith contribution to
+   this repository.
+
+   "Evaluation Period" means a single, continuous period of up to
+   thirty (30) days during which a for-profit organization may
+   internally evaluate the Software at no charge. After the Evaluation
+   Period expires, any further use of the Software by that organization
+   constitutes Commercial Use and requires a separate commercial
+   license from the Licensor.
+
+1. Permitted Use
+
+   You may, without charge:
+
+   (a) view, read, and study the source code of the Software;
+   (b) run the Software, in source or compiled form, for your own
+       Non-Commercial Use, or for Commercial Use solely within the
+       Evaluation Period;
+   (c) submit improvements to the Software back to this repository via
+       pull request, subject to Section 3 (Contributions).
+
+2. Prohibited Use
+
+   Without prior written permission from the Licensor, you may NOT:
+
+   (a) make any Commercial Use of the Software, in whole or in part,
+       except during the Evaluation Period as defined in Section 0;
+   (b) redistribute the Software, in source or compiled form, whether
+       modified or unmodified, to any third party;
+   (c) sublicense, sell, rent, lease, or otherwise transfer the
+       Software or any rights granted herein;
+   (d) remove, obscure, or alter any copyright, trademark, attribution,
+       or license notice contained in the Software;
+   (e) use the names "API Circle", "API Circle Studio", or any related
+       logos or trademarks, except as required for accurate attribution.
+
+3. Contributions
+
+   By submitting any contribution (including but not limited to code,
+   documentation, or assets) to this repository, you grant the Licensor
+   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
+   license to use, modify, distribute, and relicense your contribution
+   under any terms, including the terms of this license or any future
+   version thereof.
+
+4. No Trademark License
+
+   This license does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except
+   as required for reasonable and customary use in describing the
+   origin of the Software.
+
+5. Termination
+
+   The rights granted in Section 1 terminate automatically if you
+   breach any term of this license. Upon termination, you must cease
+   all use of the Software and destroy all copies in your possession.
+
+6. Disclaimer of Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+8. Commercial Licensing
+
+   For commercial licensing, redistribution, or any use not permitted
+   under Section 1, contact: apicircle365@gmail.com

package/README.md

@@ -4,25 +4,97 @@
 
 <h1 align="center">@apicircle/mock-server-core</h1>
 
-Hono-based mock-server engine for [API Circle Studio](https://github.com/apicircle/studio). Parses OpenAPI / Swagger / Postman / Insomnia files into a `MockEndpoint[]`, then serves them on Node, Bun, or any edge runtime that runs Hono.
+<p align="center">
+  <strong>Turn any OpenAPI, Postman, Insomnia, or Swagger file into a real, running HTTP server — in three lines of code.</strong><br />
+  Built on Hono. Runs on Node, Bun, Deno, and every edge runtime Hono supports.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@apicircle/mock-server-core"><img src="https://img.shields.io/npm/v/@apicircle/mock-server-core?color=cb3837&logo=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/parses-OpenAPI%203%20%C2%B7%20Swagger%202%20%C2%B7%20Postman%20v2.x%20%C2%B7%20Insomnia%20v4-blue" alt="Parsers" />
+  <img src="https://img.shields.io/badge/runtime-Hono-orange" alt="Hono" />
+  <img src="https://img.shields.io/badge/runtimes-Node%20%C2%B7%20Bun%20%C2%B7%20Edge-success" alt="Runtimes" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen" alt="Node ≥ 20" />
+</p>
+
+---
+
+## Why a developer would reach for this
+
+You have a spec, and you need a server that responds **right now** — before
+the backend team merges anything, before staging is provisioned, before a
+mobile build can hit it on a flight.
+
+`@apicircle/mock-server-core` is the engine that ships with API Circle Studio,
+extracted as a standalone npm package. Point it at your spec; get a real HTTP
+server. No config DSL, no YAML rules file, no Docker image.
+
+```ts
+import { startMockServer, parseSourceToEndpoints } from '@apicircle/mock-server-core';
+
+const { endpoints } = await parseSourceToEndpoints({
+  kind: 'openapi',
+  spec: rawYamlOrJson,
+  format: 'yaml',
+});
+
+const mock = await startMockServer({ name: 'Petstore', endpoints, defaultPort: 4040 });
+// → POST http://localhost:4040/pets, GET http://localhost:4040/pets/{id}, ...
+```
+
+That's the whole API surface for the simple case. Everything below is what
+makes the simple case scale.
+
+## What makes it different
+
+- **Four importers, one output shape.** OpenAPI 3.x, Swagger 2.0, Postman
+  v2/v2.1, and Insomnia v4 all reduce to the same typed `MockEndpoint[]`.
+  Swap your team's spec format and nothing downstream changes.
+- **Built on Hono.** A 14 kB router with native support for Node, Bun, Deno,
+  Cloudflare Workers, Vercel Edge, Lambda, and more. Run mocks in CI, in a
+  desktop app, on a developer's laptop, or behind a tunnel — same code.
+- **Per-endpoint overrides.** Inject error responses, custom headers, delays,
+  or bespoke bodies on a single endpoint without touching the source spec.
+  Perfect for testing error paths and slow networks.
+- **Real example bodies.** Postman? Picks the first saved response. OpenAPI?
+  Uses the `example` / `examples` / `default` from the spec. No `"string"`
+  / `0` placeholder data — what's in the spec is what you get.
+- **CORS, on by default.** Browser-friendly out of the box, configurable when
+  you need to lock it down.
+- **Strict $ref resolution.** OpenAPI parsing flows through
+  [`@apidevtools/swagger-parser`](https://www.npmjs.com/package/@apidevtools/swagger-parser)
+  for compliant dereferencing — `$ref` chains, recursive schemas, file refs.
 
 ## Install
 
 ```bash
 npm install @apicircle/mock-server-core
+# pnpm add @apicircle/mock-server-core
 ```
 
+Pulls in Hono and the swagger parser; no native modules.
+
 ## Quickstart
 
+### 1. Parse a spec
+
 ```ts
-import { startMockServer, parseSourceToEndpoints } from '@apicircle/mock-server-core';
+import { parseSourceToEndpoints } from '@apicircle/mock-server-core';
 
 const { endpoints, warnings } = await parseSourceToEndpoints({
-  kind: 'openapi',
+  kind: 'openapi', // 'openapi' | 'postman' | 'insomnia' | 'manual'
   spec: rawYamlOrJson,
-  format: 'yaml',
+  format: 'yaml', // 'yaml' | 'json'
 });
 
+warnings.forEach((w) => console.warn(w));
+```
+
+### 2. Start the server
+
+```ts
+import { startMockServer } from '@apicircle/mock-server-core';
+
 const handle = await startMockServer({
   id: 'm1',
   name: 'Petstore',
@@ -35,20 +107,79 @@ const handle = await startMockServer({
   updatedAt: new Date().toISOString(),
 });
 
-// later
+console.log(handle.url); // http://localhost:4040
+```
+
+### 3. Override one endpoint
+
+```ts
+await startMockServer({
+  // ...
+  overrides: {
+    [endpoints[0].id]: {
+      status: 503,
+      headers: { 'Retry-After': '30' },
+      delayMs: 1200,
+    },
+  },
+});
+```
+
+Per-endpoint overrides are how you simulate flaky backends, rate-limiters,
+slow regions, and "what does the app do when this call returns 500?".
+
+### 4. Stop it
+
+```ts
 await handle.close();
 ```
 
-## What it parses
+## Format support matrix
+
+| Format   | Versions   | What we pull out                                             |
+| -------- | ---------- | ------------------------------------------------------------ |
+| OpenAPI  | 3.0, 3.1   | Path + method, parameters, request bodies, example responses |
+| Swagger  | 2.0        | Same, dereferenced via `@apidevtools/swagger-parser`         |
+| Postman  | v2.0, v2.1 | Recursive item walks; first saved response → fallback 200    |
+| Insomnia | v4 export  | Filters `_type: 'request'`                                   |
+| Manual   | n/a        | Hand-rolled `MockEndpoint[]` you build yourself              |
+
+## Where it runs
+
+Because the engine is just a Hono app builder, anywhere Hono runs, this runs:
+
+- **Node** ≥ 20 — the common case, used by the API Circle Studio desktop app.
+- **Bun** — single-binary mocks in CI.
+- **Cloudflare Workers / Vercel Edge / Deno Deploy** — public, always-on mocks
+  served from the edge.
+- **Lambda** — pay-per-request mock servers for short-lived environments.
+
+## Use cases
+
+- **Unblock the frontend** while the backend is still being designed.
+- **Spin up CI mocks** for integration tests without a docker-compose file.
+- **Demo a public API** to prospects before the rate-limited beta is ready.
+- **Reproduce production bugs** by overriding one endpoint with the exact
+  response that broke the client.
+- **Power AI agents** — let an LLM drive a real HTTP server it can probe.
+
+## Where it fits
+
+```
+@apicircle/shared              (types + utilities)
+└── @apicircle/mock-server-core ◀── you are here
+    └── @apicircle/cli         (`apicircle mock ./spec.yaml`)
+    └── @apicircle/mcp-server  (mock.start / mock.stop tools)
+```
 
-- **OpenAPI 3.x and Swagger 2.0** — JSON or YAML, including `$ref` deref via `@apidevtools/swagger-parser`.
-- **Postman v2 / v2.1 collections** — recursive item walks, picks first saved response, falls back to a 200 default.
-- **Insomnia v4 exports** — filters resources of `_type: 'request'`.
-- **Manual** — pre-built `MockEndpoint[]` you supply yourself.
+The exact same factory powers the desktop `MockManager`, the
+`apicircle mock` CLI command, and the MCP `mock.start` tool. One engine,
+three runtimes.
 
-## Per-endpoint overrides
+## Learn more
 
-`MockServer.overrides[endpointId]` lets you change status, headers, body, or delay for a single endpoint without touching the source spec — perfect for testing error paths.
+- **Full mock server guide**: <https://github.com/apicircle/studio/blob/main/docs/mock-server.md>
+- **Hono docs**: <https://hono.dev>
 
 ## License
 

package/dist/index.cjs

@@ -1002,6 +1002,7 @@ async function isPortFree(port) {
 }
 
 // src/runtime/nodeAdapter.ts
+var CLOSE_TIMEOUT_MS = 3e3;
 async function serveOnNode(app, opts = {}) {
   const port = opts.port && opts.port > 0 ? opts.port : await getFreePort();
   const host = opts.host ?? "127.0.0.1";
@@ -1023,12 +1024,24 @@ async function serveOnNode(app, opts = {}) {
   });
   return {
     port,
-    close: () => new Promise((resolve, reject) => {
+    close: () => new Promise((resolve) => {
       if (!server) return resolve();
-      server.close((err) => {
-        if (err) reject(err);
-        else resolve();
-      });
+      const s = server;
+      const withCloseHelpers = s;
+      try {
+        withCloseHelpers.closeIdleConnections?.();
+        withCloseHelpers.closeAllConnections?.();
+      } catch {
+      }
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(settle, CLOSE_TIMEOUT_MS);
+      s.close(() => settle());
     })
   };
 }