@tetsujs/openapi 0.4.0 → 0.4.2

package/README.md

@@ -30,6 +30,38 @@ reported before the first request.
 prefix, guard it with hooks, or leave it out in production. Its own two
 routes are left out of the document.
 
+### The page runs someone else's code on your origin
+
+The page loads its renderer — Scalar, Swagger UI or Redoc — from
+jsDelivr and runs it on the application's origin, with that origin's
+cookies. If a session cookie lives there, a renderer that is not what it
+should be acts as the signed-in user. The defaults are pinned to an exact
+version with a Subresource Integrity hash, so a file the CDN changes is
+refused by the browser; that does not make the renderer yours, and what it
+loads in turn is not covered.
+
+Where the origin carries a session, serve the document alone:
+
+```ts
+docs({ info, ui: false });
+```
+
+`/openapi.json` is served and there is no page. For a page anyway, host
+the renderer yourself or pin your own copy, with its hash:
+
+```ts
+docs({
+  info,
+  assets: {
+    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js",
+    integrity: { script: "sha384-…" },
+  },
+});
+```
+
+`curl -s <url> | openssl dgst -sha384 -binary | openssl base64 -A` prints
+the hash, to be prefixed with `sha384-`.
+
 ## Options
 
 | Option | Default | |
@@ -38,9 +70,9 @@ routes are left out of the document.
 | `servers` | — | where the API is reachable |
 | `path` | `/openapi.json` | where the document is served |
 | `uiPath` | `/docs` | where the page is served |
-| `ui` | `"scalar"` | `"scalar"`, `"swagger-ui"` or `"redoc"` |
+| `ui` | `"scalar"` | `"scalar"`, `"swagger-ui"`, `"redoc"`, or `false` for no page |
 | `title` | the document's title | the page's title |
-| `assets` | the renderer's CDN | pinned or self-hosted renderer URLs |
+| `assets` | the renderer on jsDelivr, pinned | your own renderer URLs, with `integrity` hashes |
 | `documentSelf` | `false` | include `/openapi.json` and `/docs` in the document |
 | `onWarning` | `console.warn` | receives what could not be described |
 
@@ -106,6 +138,19 @@ The `error` code is a constant in each schema, so a generated client can
 tell failures apart by it. A status the route declares itself is kept, and
 the framework's failures for the same status are listed next to it.
 
+Every envelope — the framework's, a hook's, or one the route declares
+itself — is one definition in `components` per status and code, named
+after the code (`ITEM_NOT_FOUND` is `ItemNotFound`), so a generated client
+gets one type per failure. A schema is recognized as an envelope when its
+`error` is required and a single string. When the route and a hook both
+describe one code, the route's definition is kept; if the other one has
+different fields, the generator warns. A union the route declares joins
+the other failures of its status as one flat `anyOf`.
+
+When every alternative of a status is an envelope, the union carries a
+`discriminator` on `error`, with the mapping from each code to its
+definition, and a generated client narrows on the code.
+
 ## Documenting hooks
 
 A hook that answers by itself — an auth check, a limiter — can say so, and
@@ -127,14 +172,48 @@ export const auth = secured(
 );
 
 export const guard = documented(hook.beforeParse(check), {
-  responses: [{ status: 429, description: "Rate limit exceeded", error: "RATE_LIMITED" }],
+  responses: [
+    {
+      status: 429,
+      description: "Rate limit exceeded",
+      error: "RATE_LIMITED",
+      fields: { retryAfter: { type: "integer", minimum: 0 } },
+      headers: { "retry-after": { schema: { type: "integer", minimum: 0 } } },
+    },
+  ],
 });
 ```
 
+A response with an `error` code is the framework's envelope, defined once
+in `components` and named after the code. `fields` adds what the hook puts
+next to `status`, `message` and `error`, each always present; `headers`,
+what it sets on the response. Both are JSON Schema written by hand, typed
+keyword by keyword (`JsonSchema`), so a misspelled keyword does not
+compile. A hook whose body is not the envelope passes a `schema` instead.
+
 Hooks from `@tetsujs/rate-limit` are already documented this way. A scheme
 is identified by its `name`: the same one mounted twice is one
 requirement, and two different schemes under one name are reported.
 
+Every hook of a route runs, so every scheme its hooks carry is required
+together: a route behind a CSRF check and a captcha is documented as
+needing both, one entry of `security` — in OpenAPI, separate entries mean
+any one of them will do. Two hooks of one scheme require the scopes of
+both.
+
+"Either" lives inside one hook: a hook that accepts a session cookie or a
+bearer token says so with `anyOf`, and the document lists every
+combination a client may bring:
+
+```ts
+export const caller = secured(hook.beforeParse(sessionOrToken), {
+  anyOf: [cookieSession, bearerToken],
+});
+
+// with a CSRF check on the same route:
+// security: [{ session: [], csrf: [] }, { bearer: [], csrf: [] }]
+```
+
 ## Using the document directly
 
 When the document itself is the output — written to a file in CI, fed to a

package/dist/src/annotations.d.ts

@@ -16,15 +16,16 @@
  * @module
  */
 import type { AnyHook, AnySchema } from "@tetsujs/core";
+import type { JsonSchema } from "./json-schema.ts";
 /**
  * The definition of a scheme, as OpenAPI spells it.
  *
- * Typed as loosely as the spec is wide — `http`, `apiKey`, `oauth2` and
- * `openIdConnect` carry different fields, and narrowing them here would
- * be a second, poorer copy of the specification.
+ * Typed as loosely as the spec is wide — `http`, `apiKey`, `oauth2`,
+ * `openIdConnect` and `mutualTLS` carry different fields, and narrowing
+ * them here would be a second, poorer copy of the specification.
  */
 export interface SecurityScheme {
-    readonly type: "http" | "apiKey" | "oauth2" | "openIdConnect";
+    readonly type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
     readonly [key: string]: unknown;
 }
 /** What a hook demands of a request, and what it answers when refused. */
@@ -70,11 +71,65 @@ export interface DocumentedResponse {
     readonly error?: string;
     /** An example of the envelope's `message`, for the same reason. */
     readonly message?: string;
+    /**
+     * Fields the hook adds to the envelope, as JSON Schema by name — the
+     * `retryAfter` of `{ ...errorBody(429, "RATE_LIMITED"), retryAfter }`.
+     *
+     * Each is documented as always present. The envelope's own `status`,
+     * `message` and `error` are not redefined by a field of the same name:
+     * `error` is what a client discriminates on, and it stays the code the
+     * hook declared. Ignored when the response has a `schema`, which says
+     * everything about the body itself.
+     *
+     * @example
+     * ```ts
+     * documented(limiter, {
+     *   responses: [
+     *     {
+     *       status: 429,
+     *       description: "Too many requests",
+     *       error: "RATE_LIMITED",
+     *       fields: { retryAfter: { type: "integer", minimum: 0 } },
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    readonly fields?: Readonly<Record<string, JsonSchema>>;
+    /**
+     * Headers the hook sets on this response, by name — the `retry-after`
+     * of a refusal.
+     *
+     * Documented as possible rather than required: a status several sources
+     * answer with is one response in the document, and a header one of them
+     * sets is not on the others'.
+     */
+    readonly headers?: Readonly<Record<string, DocumentedHeader>>;
+}
+/** A header a hook's response carries. */
+export interface DocumentedHeader {
+    readonly description?: string;
+    readonly schema: JsonSchema;
+}
+/**
+ * Requirements of which a hook accepts any one: a session cookie *or* a
+ * bearer token, checked by one hook.
+ *
+ * "Either" lives inside a hook, never between hooks — every hook of a
+ * route runs, so the schemes of two hooks are both required. A hook that
+ * takes either of two credentials says so here, and the document lists
+ * the combinations a client may bring.
+ */
+export interface SecurityAlternatives {
+    readonly anyOf: readonly SecurityRequirement[];
 }
 /** Everything a hook tells the generator about itself. */
 export interface HookDocs {
-    /** What the hook demands of a request. */
-    readonly security?: SecurityRequirement;
+    /**
+     * What the hook demands of a request: one requirement, or alternatives
+     * of which any one will do.
+     */
+    readonly security?: SecurityRequirement | SecurityAlternatives;
     /** What the hook can answer with. */
     readonly responses?: readonly DocumentedResponse[];
 }
@@ -100,6 +155,10 @@ export declare function documented<H extends AnyHook>(hook: H, docs: HookDocs):
  * Annotates a hook with the security it enforces — {@link documented} for
  * the case that comes up most.
  *
+ * One requirement, or `{ anyOf: [...] }` for a hook that accepts any one
+ * of several: the schemes of different hooks are all required, the
+ * alternatives of one hook are not.
+ *
  * @example
  * ```ts
  * export const auth = secured(
@@ -114,15 +173,37 @@ export declare function documented<H extends AnyHook>(hook: H, docs: HookDocs):
  *   },
  * );
  * ```
+ *
+ * @example A hook that accepts a session cookie or a bearer token
+ * ```ts
+ * export const caller = secured(
+ *   hook.beforeParse((ctx) => {
+ *     const user = sessions.fromCookie(ctx) ?? tokens.fromHeader(ctx);
+ *     if (!user) throw new HttpError(401);
+ *     return { user };
+ *   }),
+ *   { anyOf: [cookieSession, bearerToken] },
+ * );
+ * ```
  */
-export declare function secured<H extends AnyHook>(hook: H, requirement: SecurityRequirement): H;
+export declare function secured<H extends AnyHook>(hook: H, requirement: SecurityRequirement | SecurityAlternatives): H;
 /** Reads everything a hook was annotated with. */
 export declare function docsOf(hook: AnyHook): HookDocs | undefined;
-/** Reads the security requirement a hook carries, if it carries one. */
-export declare function securityOf(hook: AnyHook): SecurityRequirement | undefined;
+/** Reads the security a hook was annotated with, if it was. */
+export declare function securityOf(hook: AnyHook): SecurityRequirement | SecurityAlternatives | undefined;
 /** What the hooks of one route contribute, in execution order. */
 export interface HookContributions {
+    /**
+     * Every scheme the hooks mention, once per name, with the scopes of all
+     * of them: what the document registers, and what a refusal answers with.
+     */
     readonly security: readonly SecurityRequirement[];
+    /**
+     * What a request must satisfy, one condition per hook: every condition
+     * is required, and any one requirement of a condition satisfies it. A
+     * hook with one requirement is a condition of one.
+     */
+    readonly conditions: readonly (readonly SecurityRequirement[])[];
     readonly responses: readonly DocumentedResponse[];
 }
 /**
@@ -130,7 +211,9 @@ export interface HookContributions {
  *
  * A scheme is registered once per name and a response once per status and
  * description: the same guard on the application and on a group is one
- * requirement, not two.
+ * requirement, not two. Two hooks of one scheme asking for different
+ * scopes both run, so the requirement asks for the scopes of both — each
+ * once, in the order they were first asked for.
  *
  * Deduplicating by name means two hooks claiming one name with different
  * schemes lose one of them, and that is not a duplicate being collapsed —

package/dist/src/annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,CAAC;IAC9D,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAExC,qCAAqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,CAAC,CASxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,IAAI,EAAE,CAAC,EACP,WAAW,EAAE,mBAAmB,GAC/B,CAAC,CAEH;AAED,kDAAkD;AAClD,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAE1D;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAEzE;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,EAC1C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC/B,iBAAiB,CAyCnB"}
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/annotations.ts"],"names":[],"mappings":"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"}

package/dist/src/controller.d.ts

@@ -18,7 +18,7 @@ import type { OpenApiDocument } from "./document.ts";
 import type { GeneratorWarning } from "./index.ts";
 import type { DocsAssets, DocsUi } from "./page.ts";
 /** What the documentation controller serves, and from where. */
-export interface DocsOptions<Path extends string, UiPath extends string> {
+export interface DocsOptions<Path extends string, UiPath extends string, Ui extends DocsUi | false = DocsUi | false> {
     /** Title, version and the rest of the document's `info` block. */
     readonly info: OpenApiDocument["info"];
     /** Servers the API is reachable at. */
@@ -27,8 +27,16 @@ export interface DocsOptions<Path extends string, UiPath extends string> {
     readonly path?: Path & ValidatePath<Path>;
     /** Where the page is served. Defaults to `/docs`. */
     readonly uiPath?: UiPath & ValidatePath<UiPath>;
-    /** Which renderer the page bootstraps. Defaults to `"scalar"`. */
-    readonly ui?: DocsUi;
+    /**
+     * Which renderer the page bootstraps. Defaults to `"scalar"`.
+     *
+     * `false` serves the document without a page — what production wants
+     * on an origin that carries a session. The page runs its renderer on the
+     * application's origin, so a renderer that is not what it should be acts
+     * in the signed-in user's name there; the document alone runs nothing.
+     * `uiPath`, `title` and `assets` are then unused.
+     */
+    readonly ui?: Ui;
     /** Browser title of the page. Defaults to the document's own title. */
     readonly title?: string;
     /** Overrides the renderer's CDN URLs, for a pinned or self-hosted copy. */
@@ -56,15 +64,24 @@ export interface DocsOptions<Path extends string, UiPath extends string> {
  * Instantiated through the factory, never directly — the routes carry the
  * configured paths in their types, which only the factory can infer.
  */
-export declare class DocsController<Path extends string, UiPath extends string> {
+export declare class DocsController<Path extends string, UiPath extends string, Page extends boolean = true> {
     private readonly options;
     /** The document itself, as `application/json`. */
     readonly json: RouteDef<Path, SchemaConfig, never, undefined, "GET">;
-    /** The page that renders it. */
-    readonly ui: RouteDef<UiPath, SchemaConfig, never, undefined, "GET">;
+    /** The page that renders it — none with `ui: false`. */
+    readonly ui: Page extends true ? RouteDef<UiPath, SchemaConfig, never, undefined, "GET"> : undefined;
     private document;
-    constructor(options: DocsOptions<Path, UiPath>, documentPath: string, uiPath: string, page: string);
-    /** Generates the document of the application this was mounted in. */
+    private page;
+    constructor(options: DocsOptions<Path, UiPath>, documentPath: string, uiPath: string);
+    /**
+     * Generates the document of the application this was mounted in, and
+     * the page that renders it.
+     *
+     * The page is built here rather than with the routes because only the
+     * application knows where the document ended up: a group this controller
+     * is mounted under prefixes its path, and a page pointing at the path as
+     * configured would fetch a `404`.
+     */
     [onMount](app: App): void;
 }
 /**
@@ -87,5 +104,5 @@ export declare class DocsController<Path extends string, UiPath extends string>
  * The page loads its renderer from a CDN; see {@link docsPage} for the
  * trade and for how to point it at a self-hosted copy.
  */
-export declare function docs<const Path extends string = "/openapi.json", const UiPath extends string = "/docs">(options: DocsOptions<Path, UiPath>): DocsController<Path, UiPath>;
+export declare function docs<const Path extends string = "/openapi.json", const UiPath extends string = "/docs", const Ui extends DocsUi | false = "scalar">(options: DocsOptions<Path, UiPath, Ui>): DocsController<Path, UiPath, Ui extends false ? false : true>;
 //# sourceMappingURL=controller.d.ts.map

package/dist/src/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAS,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD,gEAAgE;AAChE,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IACrE,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEhD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAErB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IAUlE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,gCAAgC;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,OAAO,CAAC,QAAQ,CAA8B;IAE9C,YACmB,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EACnD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAgCb;IAED,qEAAqE;IACrE,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAaxB;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAClB,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,eAAe,EAC3C,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,OAAO,EACrC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAYlE"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAS,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD,gEAAgE;AAChE,MAAM,WAAW,WAAW,CAC1B,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,EACrB,EAAE,SAAS,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK;IAE1C,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;IAEjB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CACzB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,EACrB,IAAI,SAAS,OAAO,GAAG,IAAI;IAezB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAb1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,IAAI,SAAS,IAAI,GAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,GACvD,SAAS,CAAC;IAEd,OAAO,CAAC,QAAQ,CAA8B;IAE9C,OAAO,CAAC,IAAI,CAAqB;IAEjC,YACmB,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EACnD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EAkCf;IAED;;;;;;;;OAQG;IACH,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CA0BxB;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAClB,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,eAAe,EAC3C,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,OAAO,EACrC,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,KAAK,GAAG,QAAQ,EAE1C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,GACrC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,CAM/D"}

package/dist/src/document.d.ts

@@ -14,6 +14,7 @@
  *
  * @module
  */
+import type { JsonSchema } from "./json-schema.ts";
 /** Metadata every OpenAPI document must carry. */
 export interface DocumentInfo {
     readonly title: string;
@@ -38,9 +39,15 @@ export interface ParameterObject {
 export type ContentMap = Record<string, {
     readonly schema?: Record<string, unknown>;
 }>;
+/** A header a response carries. */
+export interface HeaderObject {
+    readonly description?: string;
+    readonly schema: JsonSchema;
+}
 /** One response of an operation. */
 export interface ResponseObject {
     readonly description: string;
+    readonly headers?: Record<string, HeaderObject>;
     readonly content?: ContentMap;
 }
 /** One endpoint: a method on a path. */

package/dist/src/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAC7B,MAAM,EACN;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAC9C,CAAC;AAEF,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IAEF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAC7B,MAAM,EACN;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAC9C,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IAEF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

package/dist/src/emit.d.ts

@@ -6,13 +6,15 @@
  * @module
  */
 /**
- * A JSON Schema as the generator reads it: any keyword, with the two it
+ * A JSON Schema as the generator reads it: any keyword, with the ones it
  * looks into named, so reading them does not depend on the reader's
  * `noPropertyAccessFromIndexSignature`.
  */
 export interface JsonSchemaObject {
     properties?: unknown;
     required?: unknown;
+    anyOf?: unknown;
+    oneOf?: unknown;
     [keyword: string]: unknown;
 }
 /** Which shape of a schema to describe: what arrives, or what leaves. */

package/dist/src/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}

package/dist/src/envelopes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Error envelopes, one definition per status and code.
+ *
+ * An envelope reaches a document from four directions: a route's response
+ * map, a hook's annotation, a guard's security requirement, and the
+ * framework's own failures. Each used to be described where it arrived —
+ * a route's inline, the rest by reference — so one `UNAUTHORIZED` could be
+ * listed twice under one status, once as a `$ref` and once as the same
+ * shape without a name, and a generated client got a named type next to an
+ * anonymous twin.
+ *
+ * Here every envelope, whoever declared it, becomes a reference to the
+ * one definition of its status and code. That is also what makes a status
+ * discriminable: a client can branch on `error` only if every code under
+ * the status has exactly one shape.
+ *
+ * The route's definition wins. It is the author's own contract — usually
+ * the stricter one, a validator's `additionalProperties: false` — where a
+ * hook's is the framework's generic envelope. The routes are therefore
+ * read first, before any operation is built, so the winner does not depend
+ * on which route happens to come first in the table.
+ *
+ * Internal to the package.
+ *
+ * @module
+ */
+import type { SchemaComponents, SchemaRef } from "./components.ts";
+import type { JsonSchemaObject } from "./emit.ts";
+/** The definitions of every envelope of one document. */
+export interface Envelopes {
+    /**
+     * Records a route's definition, before anything is referenced. The first
+     * route to declare a status and code defines it.
+     */
+    declare(status: number, code: string, schema: JsonSchemaObject): void;
+    /**
+     * The reference to the definition of a status and code.
+     *
+     * `schema` is how the caller describes it. When a definition already
+     * exists, that is what is referenced; if the caller's differs from it
+     * in fields, `warn` hears about it — once per document, not once per
+     * operation the hook runs on.
+     */
+    ref(status: number, code: string, schema: JsonSchemaObject, warn: (message: string) => void): SchemaRef;
+    /**
+     * The code a reference stands for, when it is one this handed out — what
+     * a discriminator maps back from.
+     */
+    codeOf(ref: string): string | undefined;
+}
+export declare function envelopes(components: SchemaComponents): Envelopes;
+/**
+ * The error code of a schema that is an envelope: an object whose `error`
+ * is required and holds one string — a `const`, or an `enum` of one value.
+ *
+ * Read off what the validator emitted, not off a declaration: the route
+ * has no other way to say which of its responses is an envelope, and the
+ * shape is what a client would branch on anyway.
+ */
+export declare function envelopeCode(schema: JsonSchemaObject): string | undefined;
+/**
+ * The alternatives a schema stands for, as a list the status's own union
+ * can take in.
+ *
+ * `anyOf` nested in `anyOf` says nothing its branches do not say side by
+ * side, so a schema that is only an `anyOf` is replaced by its branches.
+ * A `oneOf` is different — "exactly one" of two overlapping shapes refuses
+ * what both accept — and is taken apart only when its branches cannot
+ * overlap: envelopes with a different code each. A schema with anything
+ * beside its union, a `title` or a `$defs`, is left whole: those keywords
+ * belong to the union, and would be lost with it.
+ */
+export declare function branchesOf(schema: JsonSchemaObject): JsonSchemaObject[];
+//# sourceMappingURL=envelopes.d.ts.map

package/dist/src/envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,SAAS,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAoEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CA0BzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAwBvE"}

package/dist/src/index.d.ts

@@ -20,11 +20,12 @@
  */
 import type { App } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
-export type { DocumentedResponse, HookContributions, HookDocs, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
+export type { DocumentedHeader, DocumentedResponse, HookContributions, HookDocs, SecurityAlternatives, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
 export { documented, secured } from "./annotations.ts";
 export type { DocsOptions } from "./controller.ts";
 export { DocsController, docs } from "./controller.ts";
-export type { ContentMap, DocumentInfo, DocumentServer, OpenApiDocument, OperationObject, ParameterObject, PathItemObject, ResponseObject, } from "./document.ts";
+export type { ContentMap, DocumentInfo, DocumentServer, HeaderObject, OpenApiDocument, OperationObject, ParameterObject, PathItemObject, ResponseObject, } from "./document.ts";
+export type { JsonSchema, JsonSchemaKeywords, JsonSchemaType, } from "./json-schema.ts";
 export type { DocsAssets, DocsPageOptions, DocsUi } from "./page.ts";
 export { docsPage } from "./page.ts";
 /**

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAIrE,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAsF1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAKrE,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA2F1E"}