@croutonian/with-openapi 0.2.0 → 0.3.0

package/README.md

@@ -129,6 +129,16 @@ callback before that response is built:
 | `unsupported_media_type` | 415    | The body's content type is not in the operation's `content`.            |
 | `validation_failed`      | 400    | A parameter or body failed its schema.                                  |
 
+`route_not_found` says which of its two causes it was, because they are the
+same status and very different mistakes — a `basePath` nothing starts with
+turns every route into a 404, and blaming the document sends you looking for a
+path that is already in it:
+
+```
+no operation in the API description matches "/nope"
+the pathname "/users/me" is outside basePath "/api/v1"
+```
+
 The default body:
 
 ```json
@@ -213,7 +223,16 @@ handy for customizing one kind and leaving the rest alone.
 entry in the document:
 
 - `GET /reference` — the HTML page
-- `GET /reference/openapi.json` — the document, for the page to load
+- `GET /openapi.json` — the document, for the page to load
+
+Both defaults are derived from `basePath`, so under `basePath: '/api'` they are
+`/api/reference` and `/api/openapi.json`. A reference outside the mount is
+usually unreachable rather than merely unconventional: a host that routes only
+`/api/*` to this handler can never produce a pathname of `/reference`.
+
+The document path is derived from the mount, **not** from `path` — the document
+is the artifact and the page is one view of it, so moving the page to `/docs`
+leaves the document where it was.
 
 ```ts
 withOpenApi({
@@ -238,11 +257,45 @@ entirely:
 
 ```ts
 reference: {
-  html: ({ documentPath }) => myOwnPage(documentPath)
+  html: ({ documentPath, documentUrl }) => myOwnPage(documentUrl)
 }
 ```
 
-The reference paths are absolute — they are **not** relative to `basePath`.
+A path you give explicitly is taken **literally** — `basePath` is not applied
+to it, so an API under `/api/v1` can still put its docs at `/docs`:
+
+```ts
+withOpenApi({ document, basePath: '/api/v1', reference: { path: '/docs' } })
+// -> /docs, not /api/v1/docs
+```
+
+Only the default is derived from the mount.
+
+### Behind a gateway that rewrites the path
+
+`documentPath` is matched against the pathname this middleware is handed.
+`documentUrl` is what the page tells the browser to fetch. They default to the
+same string, which is right until something rewrites the path in front of you —
+and then no single value works: one spelling never serves the JSON, the other
+renders a page that loads and immediately reports that it could not load the
+document.
+
+Supabase Edge Functions is that case by default. The platform routes on
+`/functions/v1/<fn>/...`, strips `/functions/v1`, and hands the worker
+`/<fn>/...`:
+
+```ts
+withOpenApi({
+  document,
+  // What the worker sees — not the public URL, and not `servers[0].url`.
+  basePath: '/api',
+  reference: {
+    path: '/api/reference',
+    documentPath: '/api/openapi.json', // where this middleware serves it
+    documentUrl: '/functions/v1/api/openapi.json', // where a browser fetches it
+  },
+})
+```
 
 ## Parameters
 
@@ -451,7 +504,7 @@ What it configures, and why each is needed:
 | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | A **GitHub App** with Contents and Pull requests write, installed on the repo, as `GH_APP_ID` + `GH_APP_PRIVATE_KEY` | release-please has to open a PR, and this org does not let GitHub Actions do that. An App is not GitHub Actions, so the policy does not cover it — and unlike `GITHUB_TOKEN`, its pushes trigger workflows, so the release PR gets CI. |
 | The **pkg.pr.new App** installed on the repo                                                                         | Branch previews. Without it the preview job warns and skips rather than failing.                                                                                                                                                       |
-| An **npm trusted publisher** for `@croutonian/with-openapi`                                                          | Publishing without a stored credential.                                                                                                                                                                                                |
+| An **npm trusted publisher** for `@croutonian/with-openapi`, with direct publish allowed                             | Publishing without a stored credential. Configurations created after 3 Sep 2026 default to staging only, and `release.yml` runs `npm publish` — stage-only would leave every release waiting in a staging area.                        |
 | The **JSR package** linked to this repository                                                                        | Same, on the JSR side.                                                                                                                                                                                                                 |
 
 To do it by hand instead, the same steps are in the comments at the top of

package/dist/index.d.ts

@@ -124,6 +124,8 @@ declare const SCALAR_CDN_URL = "https://cdn.jsdelivr.net/npm/@scalar/api-referen
 interface ScalarHtmlInput {
   /** Absolute path the document JSON is served from. */
   readonly documentPath: string;
+  /** URL the page should fetch the document from. */
+  readonly documentUrl: string;
   /** Page `<title>`. */
   readonly title: string;
   /** Script URL for Scalar's standalone build. */
@@ -137,15 +139,44 @@ interface ScalarReferenceOptions {
    * Path the HTML page is served from. Matched exactly, and *before* the
    * document's own routes, so it does not need to appear in the document.
    *
-   * @defaultValue `'/reference'`
+   * Given explicitly it is taken literally — `basePath` is **not** applied,
+   * so an API under `/api/v1` can still put its docs at `/docs`. The default
+   * is derived from `basePath` instead, because a reference sitting outside
+   * the mount is usually unreachable rather than merely unconventional: on a
+   * host that routes only `/api/*` to this handler, nothing can produce a
+   * pathname of `/reference`.
+   *
+   * @defaultValue `` `${basePath}/reference` ``, or `'/reference'` unmounted
    */
   path?: string;
   /**
-   * Path the document JSON is served from.
+   * Path the document JSON is served from. Matched against the pathname this
+   * middleware is handed.
+   *
+   * Derived from `basePath`, not from {@link path}: the document is the
+   * artifact and the page is one view of it, so moving the page does not move
+   * the document, and the conventional `/openapi.json` is where people —
+   * and tooling — look for it.
    *
-   * @defaultValue `` `${path}/openapi.json` ``
+   * @defaultValue `` `${basePath}/openapi.json` ``, or `'/openapi.json'`
    */
   documentPath?: string;
+  /**
+   * URL the page tells the browser to fetch the document from.
+   *
+   * Defaults to {@link documentPath}, which is correct whenever the pathname
+   * this middleware is handed is the one a browser can reach. Behind a gateway
+   * that rewrites the path, it is not, and the two have to be set separately:
+   * on Supabase Edge Functions the platform routes on
+   * `/functions/v1/<fn>/...` and hands the worker `/<fn>/...`, so the document
+   * is *served* at `/api/openapi.json` and *fetched* from
+   * `/functions/v1/api/openapi.json`. No single value satisfies both -- set
+   * one and the JSON never serves, set the other and the page loads and then
+   * reports that it could not load the document.
+   *
+   * @defaultValue {@link documentPath}
+   */
+  documentUrl?: string;
   /** Page title. @defaultValue the document's `info.title`, or `'API Reference'` */
   title?: string;
   /** Script URL for Scalar's standalone build. @defaultValue {@link SCALAR_CDN_URL} */
@@ -153,7 +184,7 @@ interface ScalarReferenceOptions {
   /**
    * Extra options merged into the `Scalar.createApiReference` config — theme,
    * `darkMode`, `proxyUrl`, and anything else Scalar accepts. `url` is set
-   * from {@link documentPath} and can be overridden here.
+   * from {@link documentUrl} and can be overridden here.
    *
    * @see https://scalar.com/products/api-references/configuration
    */
@@ -208,6 +239,13 @@ interface OpenApiRejection {
   readonly method: string;
   /** The request's pathname, before `basePath` is stripped. */
   readonly pathname: string;
+  /**
+   * A more specific explanation than the kind's stock wording, when there is
+   * one to give. `route_not_found` uses it to say whether the pathname missed
+   * `basePath` or matched no template under it, which are the same status and
+   * very different mistakes.
+   */
+  readonly message?: string;
   /** Path template that matched, when one did. */
   readonly route?: string;
   /** Methods the route does declare. Set on `method_not_allowed`. */
@@ -316,7 +354,7 @@ interface WithOpenApiConfig {
   /**
    * Serve a Scalar API reference and the document JSON. `true` takes every
    * default — the page at `/reference`, the document at
-   * `/reference/openapi.json`.
+   * `/openapi.json`.
    *
    * @defaultValue off
    */

package/dist/index.js

@@ -868,18 +868,20 @@ function joinPath(base, child) {
 	return `${base.endsWith("/") ? base.slice(0, -1) : base}/${child}`;
 }
 /** Fill in the reference endpoint's defaults, once, at construction. */
-function resolveReference(document, options) {
-	const path = options.path ?? "/reference";
+function resolveReference(document, options, basePath) {
+	const path = options.path ?? joinPath(basePath ?? "", "reference");
 	if (!path.startsWith("/")) throw new Error(`withOpenApi: reference.path must start with "/", got ${JSON.stringify(path)}`);
-	const documentPath = options.documentPath ?? joinPath(path, "openapi.json");
+	const documentPath = options.documentPath ?? joinPath(basePath ?? "", "openapi.json");
+	const documentUrl = options.documentUrl ?? documentPath;
 	const title = options.title ?? document.info?.title ?? "API Reference";
 	const cdnUrl = options.cdnUrl ?? SCALAR_CDN_URL;
 	const configuration = {
-		url: documentPath,
+		url: documentUrl,
 		...options.configuration
 	};
 	const page = (options.html ?? renderScalarHtml)({
 		documentPath,
+		documentUrl,
 		title,
 		cdnUrl,
 		configuration
@@ -887,6 +889,7 @@ function resolveReference(document, options) {
 	return {
 		path,
 		documentPath,
+		documentUrl,
 		cacheControl: options.cacheControl ?? "no-cache",
 		render: () => page
 	};
@@ -1151,7 +1154,7 @@ function defaultRejectionResponse(rejection) {
 	if (rejection.allow !== void 0 && rejection.allow.length > 0) headers.set("allow", rejection.allow.join(", "));
 	return Response.json({
 		error: rejection.kind,
-		message: REJECTION_MESSAGES[rejection.kind],
+		message: rejection.message ?? REJECTION_MESSAGES[rejection.kind],
 		...rejection.accepts === void 0 ? {} : { accepts: rejection.accepts },
 		violations: rejection.violations
 	}, {
@@ -1246,7 +1249,7 @@ const withOpenApi = defineMiddleware({
 		const onUnknownMethod = config.onUnknownMethod ?? "reject";
 		const resolve = (schema) => resolveSchema(document, schema);
 		const validateSchema = options === void 0 ? void 0 : createSchemaValidator(document, config.schemaDraft ?? draftFor(document));
-		const reference = config.reference === void 0 || config.reference === false ? void 0 : resolveReference(document, config.reference === true ? {} : config.reference);
+		const reference = config.reference === void 0 || config.reference === false ? void 0 : resolveReference(document, config.reference === true ? {} : config.reference, basePath);
 		const documentJson = reference === void 0 ? void 0 : JSON.stringify(document);
 		const cors = config.cors === void 0 ? void 0 : createCorsPolicy(document, routes, config.cors);
 		/**
@@ -1297,6 +1300,7 @@ const withOpenApi = defineMiddleware({
 					status: 404,
 					method: req.method,
 					pathname: url.pathname,
+					message: pathname === void 0 ? `the pathname ${JSON.stringify(url.pathname)} is outside basePath ${JSON.stringify(basePath)}` : `no operation in the API description matches ${JSON.stringify(pathname)}`,
 					violations: []
 				});
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@croutonian/with-openapi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenAPI middleware for @supabase/middleware. Matches each request against an OpenAPI 3.1 document, optionally rejects the ones it does not describe, contributes the matched operation and validated params to ctx, and optionally serves a Scalar API reference.",
   "keywords": [
     "openapi",