stitchkit 0.22.0 → 0.23.0

package/dist/server/index.js

@@ -398,6 +398,8 @@ function generateOpenApiDocument(config) {
     for (const [key, method] of Object.entries(service.methods)) {
       if (method.expose && !method.expose.includes("HTTP"))
         continue;
+      if (config.includeMethod && !config.includeMethod(method))
+        continue;
       const servicePath = joinPath("/", service.prefix, method.path === "/" ? "" : method.path);
       const fullPath = toOpenApiPath(pathPrefix ? joinPath(pathPrefix, servicePath) : servicePath);
       const parameters = [];

package/dist/server/openapi.d.ts

@@ -10,7 +10,7 @@
  * emits — not a divergent code path. Schemas are inlined (valid OpenAPI);
  * `$ref` de-duplication can come later if a spec grows unwieldy.
  */
-import type { RawRoute, ServiceDef } from './types';
+import type { MethodDef, RawRoute, ServiceDef } from './types';
 export interface OpenApiInfo {
     title: string;
     version: string;
@@ -31,6 +31,19 @@ export interface OpenApiConfig {
     }>;
     /** `servers` block for the spec. */
     servers?: OpenApiServer[];
+    /**
+     * Emit only the methods this predicate keeps — a curated public spec instead
+     * of the whole HTTP surface. The predicate decides the policy (the core stays
+     * generic): filter on `method.scope`, `method.meta` (the recommended
+     * declarative allowlist — mark endpoints `meta: { public: true }` and keep
+     * `(m) => m.meta?.public === true`), `method.key`, anything on the method.
+     * Omit to include every HTTP method (the default).
+     *
+     * This controls what the spec **advertises**, not access — a hidden endpoint
+     * is still callable; the auth `scope` gate is the actual guard. Build a
+     * separate filtered document for a public route (see the guide).
+     */
+    includeMethod?: (method: Readonly<MethodDef>) => boolean;
 }
 export interface OpenApiDocument {
     openapi: '3.1.0';
@@ -41,7 +54,9 @@ export interface OpenApiDocument {
 /**
  * Generate an OpenAPI 3.1 document from contract services. Only methods exposed
  * on HTTP are included — a method whose `expose` omits `'HTTP'` (an MCP/agent
- * only tool) is skipped, matching the router's own route-building rule.
+ * only tool) is skipped, matching the router's own route-building rule. Pass
+ * `includeMethod` to emit a curated subset (a public spec) instead of the whole
+ * surface.
  */
 export declare function generateOpenApiDocument(config: OpenApiConfig): OpenApiDocument;
 /**

package/dist/server/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAgH9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAuH9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}

package/llms-full.txt

@@ -355,7 +355,10 @@ beforeHandle: (ctx, endpoint) => {
 }
 ```
 
-`meta` is **app-private** — it is never serialized into the OpenAPI document.
+`meta` is **app-private** — it is never serialized into the OpenAPI document. It
+can still *drive* generation: `generateOpenApiDocument`'s `includeMethod` reads
+it to curate a public spec (e.g. `meta: { public: true }`), without ever emitting
+`meta` itself — see [Curating the spec](./server.md#curating-the-spec--includemethod).
 
 > **Declare a meta type as a `type`, an inline literal, or with `satisfies` — not
 > an `interface`.** A TS `interface` has no implicit index signature (it can be
@@ -856,6 +859,60 @@ bus.emit('user.created', { id: '1' })
 A typed in-process pub/sub — decouple a handler from the side effects of its
 write without reaching for an external queue.
 
+## OpenAPI
+
+`generateOpenApiDocument` builds an OpenAPI 3.1 document straight from the
+contracts — the contract *is* the spec, no decorators or hand-maintained
+annotations (→ ADR 0018). `openApiRoute` serves it as a raw route:
+
+```ts
+import { generateOpenApiDocument, openApiRoute } from 'stitchkit/server'
+
+const doc = generateOpenApiDocument({
+  info: { title: 'My API', version: '1.0.0' },
+  services: [users, orders],
+})
+createServer({ services: [users, orders], rawRoutes: [openApiRoute('/openapi.json', doc)] })
+```
+
+Only HTTP-exposed methods appear (an MCP/agent-only tool is skipped).
+
+### Curating the spec — `includeMethod`
+
+To publish a **subset** — a public spec that advertises only some methods
+without revealing the rest — pass `includeMethod`. It keeps the core generic:
+*you* decide the policy, filtering on anything the method carries. The
+recommended declarative allowlist marks endpoints with the existing `meta`
+passthrough and keeps those:
+
+```ts
+// contract — declarative, one source of truth
+getBalance: { method: 'GET', path: '/balance', desc: '…', scope: 'account',
+              meta: { public: true }, output: BalanceSchema }
+
+// generation — the app's policy
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+})
+```
+
+An excluded method's whole entry — path *and* every schema inlined within it —
+is simply never emitted, so nothing about a hidden endpoint leaks.
+
+> **The filter advertises; it does not authorize.** Hiding a method from the
+> spec does **not** protect it — it is still callable, and the auth `scope` gate
+> is the only thing guarding it. And because `openApiRoute` closes over the
+> document you hand it, the filter only matters if you feed it a filtered one:
+> serve **two** documents — a full internal spec and a filtered public spec on
+> separate routes — never one unfiltered `openApiRoute` on a public path.
+
+```ts
+const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind auth
+const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
+```
+
 
 ==============================================================================
 # Guide: Typed client  (docs/guide/client.md)
@@ -3286,7 +3343,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 |--------|------|---------|
 | `generateOpenApiDocument` | function | an OpenAPI 3.1 document from contract services — [ADR 0018](../decisions/0018-openapi-generation.md) |
 | `openApiRoute` | function | a `RawRoute` that serves the document as JSON |
-| `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` |
+| `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
 | `OpenApiDocument` | _type_ | the generated document |
 | `OpenApiInfo` | _type_ | the spec `info` block |
 | `OpenApiServer` | _type_ | a spec `servers` entry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",