@geekmidas/constructs 10.0.0-alpha.5 → 10.0.0-alpha.51

package/dist/rest-api.d.cts

@@ -1,37 +1,32 @@
-import "./Construct-C0ijr2qp.cjs";
-import "./index-AIfVzkhi.cjs";
-import { Declarable } from "./construct-interface-D9d4Gm4p.cjs";
-import "./types-BlAkSuGI.cjs";
-import { BuiltInSecuritySchemeId } from "./Endpoint-DrD8a1yH.cjs";
-import { EndpointBuilder, EndpointFactory, RemoveTrailingSlash } from "./index-B8g8POkr.cjs";
+import { i as Declarable, t as Authenticator } from "./construct-interface-B1AfqRl4.cjs";
+import { T as BuiltInSecuritySchemeId } from "./Endpoint-Bm9HjTPc.cjs";
+import { t as EndpointFactory } from "./EndpointFactory-B6eZ3RDd.cjs";
 import { EnvironmentParser } from "@geekmidas/envkit";
 import { Logger } from "@geekmidas/logger";
-import { AppSpec, ConstructName, Declaration, Dependency } from "@geekmidas/manifest";
+import { ConstructName, Declaration, Dependency } from "@geekmidas/manifest";
 import { Telescope } from "@geekmidas/telescope";
-
 //#region src/rest-api.d.ts
-
-interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
+/** The factory a surface builds its endpoints from. */
+type Endpoints = EndpointFactory<[], '', Logger>;
+export interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
   /**
-   * The app that serves this surface: where its source lives, which globs
-   * find its code, how it is run.
-   *
-   * What makes a surface a deploy unit rather than something a deploy has to
-   * be told about separately: one `RestApi` is one server. A `StaticSite` says
-   * the same thing, and the two are the same kind of statement.
-   *
-   * Normally omitted. One RestApi is one server, always — there is no mode in
-   * which a surface shares somebody else's container, because a surface that
-   * gets its process by inference gets it from whatever happened to reference
-   * it, and that was the thing worth removing.
-   *
-   * So this is an override and nothing else. Everything in it follows from
-   * this construct's id — `apps/<kebab-id>` where that directory exists, the
-   * conventional code directories under it, a port assigned in a stable
-   * order. Write one when the layout genuinely differs:
-   * `app: { path: 'services/api' }`.
+   * The app that serves this surface, relative to the workspace root —
+   * `'apps/api'`, or `'.'` in a single-app project.
+   *
+   * Required. It was inferred from the id (`apps/<kebab-id>`, or the root
+   * when no such directory existed), which meant a surface's home was
+   * whatever happened to be on disk. It is where the app's `package.json`
+   * and base `tsconfig.json` are, and which build serves this surface. It
+   * does not change discovery: constructs still load from the workspace's
+   * `constructs` glob.
    */
-  app?: AppSpec;
+  path: string;
+  /**
+   * The label it answers on under a stage's domain — `api` for
+   * `api.myapp.com`, from `deploy.domains` — and under the project locally,
+   * `api.myapp.localhost`. Absent, its id kebab-cased.
+   */
+  subdomain?: string;
   /**
    * CORS tunables. The *origins* are never here — they are read off the
    * constructs that declared an edge to this surface, which is the whole point
@@ -98,19 +93,21 @@ interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
 /**
  * What is *not* here, and why.
  *
- * `dependsOn`, `database`, `auditor` and `publisher` all inject a capability
+ * `dependsOn`, `database`, `auditor` and `.event(topic, …)` all inject a capability
  * into a handler. Putting one on the surface hands it to every route the
  * surface serves — a health check gets the database because a report needed it
  * — which is the thing least privilege forbids and the reason `.calls()` is not
- * spelled `dependsOn`. They belong to the endpoint, or to a factory branched
- * from `api.endpoints` for a group of endpoints that genuinely share them.
+ * spelled `dependsOn`. They belong to the endpoint, or to a branch —
+ * `api.database(db)` — for a group of endpoints that genuinely share them. A
+ * branch is a new factory; the surface config stays free of grants.
  *
  * `auth` is not here either: `.auth(construct)` already declares it, and a
  * second way to say the same thing is the duplication this whole model removes.
  *
  * What is left is what the *process* is rather than what a route may reach.
  */
-declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
+export declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
+  #private;
   private readonly config;
   /** Internal: how `.calls()` carries edges into the copy it returns. */
   private readonly dependencies;
@@ -146,34 +143,44 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
   readonly envParser: EnvironmentParser<{}>;
   /** The Telescope instance, when this surface was given one. */
   readonly telescope?: Telescope;
-  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>, /** Internal: how `.calls()` carries edges into the copy it returns. */
-  dependencies?: readonly Dependency[], /** Internal: how `.auth()` carries the authenticator into its copy. */
-  authenticator?: string | undefined);
+  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>,
+  /** Internal: how `.calls()` carries edges into the copy it returns. */
+  dependencies?: readonly Dependency[],
+  /** Internal: how `.auth()` carries the authenticator into its copy. */
+  authenticator?: Authenticator | undefined);
+  /** `api.get('/users')` — one route on this surface. */
+  readonly get: Endpoints['get'];
+  readonly post: Endpoints['post'];
+  readonly put: Endpoints['put'];
+  readonly patch: Endpoints['patch'];
+  readonly delete: Endpoints['delete'];
+  readonly options: Endpoints['options'];
   /**
-   * This surface's endpoint factory.
-   *
-   * `api.get('/users')` is the short form and covers most routes. Reach for
-   * this one when a *group* of endpoints shares something a single route would
-   * otherwise repeat — a database, an auditor, a publisher:
+   * A branch for a *group* of endpoints that shares what a single route would
+   * otherwise repeat — a database, an auditor, a publisher, a session:
    *
    * ```ts
-   * const audited = api.endpoints.database(db).auditor(AuditStore);
-   * export const createUser = audited.post('/users').handle(...);
+   * export const router = api.database(database);
+   * export const createUser = router.post('/users').handle(({ db }) => …);
    * ```
    *
-   * A factory branched from here keeps the surface, so its endpoints still
-   * know which API serves them. That is deliberately narrower than putting the
-   * same thing in the surface's own config: a group opts in, where a surface
-   * would grant it to every route it serves.
+   * Each returns a new factory and leaves the surface as it was. That is the
+   * whole difference from putting the same thing in the surface's config: a
+   * group opts in, where the surface would grant it to every route it serves —
+   * a health check handed the database because a profile endpoint needed it.
+   *
+   * `dependsOn` is deliberately not here. It is per endpoint, and on the
+   * surface it would read as the API depending on something, which is what
+   * `.calls()` and `.auth()` say instead.
    */
-  readonly endpoints: EndpointFactory<[], '', Logger>;
-  /** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */
-  get<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "GET", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  post<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "POST", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  put<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PUT", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  patch<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PATCH", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  delete<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "DELETE", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
-  options<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "OPTIONS", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, never, undefined, string>;
+  readonly database: Endpoints['database'];
+  readonly session: Endpoints['session'];
+  readonly auditor: Endpoints['auditor'];
+  readonly actor: Endpoints['actor'];
+  readonly authorizer: Endpoints['authorizer'];
+  readonly authorize: Endpoints['authorize'];
+  readonly rls: Endpoints['rls'];
+  readonly route: Endpoints['route'];
   /**
    * What authenticates this surface.
    *
@@ -183,12 +190,13 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    * what a request is allowed to be. A surface with two of the first is a
    * mistake; two of the second is Tuesday.
    *
-   * It records the id, not a client. Every endpoint consumes the same thing —
-   * `verify(request) → Session | null` — and that is what every provider
-   * shares, whether the server is mounted in this process, deployed beside it,
-   * or an OIDC issuer somebody else runs.
+   * It declares the id, and keeps the construct: a session callback reads from
+   * it as `auth` — `session(async ({ auth }) => auth.getSession())` — which
+   * calls the construct's `verify(headers)`. That is the one thing every
+   * provider shares, whether the server is mounted in this process, deployed
+   * beside it, or an OIDC issuer somebody else runs.
    */
-  auth(construct: Declarable): RestApi<TName, TAuthorizers>;
+  auth(construct: Authenticator): RestApi<TName, TAuthorizers>;
   /**
    * Other surfaces this one calls.
    *
@@ -215,7 +223,6 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    */
   declare(): Declaration[];
 }
-//# sourceMappingURL=rest-api.d.ts.map
 //#endregion
-export { RestApi, RestApiConfig };
+export type { Authenticator };
 //# sourceMappingURL=rest-api.d.cts.map

package/dist/rest-api.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.d.cts","names":[],"sources":["../src/rest-api.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AA2LoB,UAnJH,aAmJG,CAAA,qBAAA,SAAA,MAAA,EAAA,GAAA,SAAA,EAAA,CAAA,CAAA;EAAK;;;;;;;;;;;;;;;;;;;EAqEa,GAAA,CAAA,EA/L/B,OA+L+B;EAAA;;;;;EAIE,IAAA,CAAA,EAAA;IAIJ,MAAA,CAAA,EAAA,MAAA;IAAK,WAAA,CAAA,EAAA,OAAA;IAAA,YAAA,CAAA,EAAA,SAAA,MAAA,EAAA;IAAA,aAAA,CAAA,EAAA,SAAA,MAAA,EAAA;EAAA,CAAA;EAAA;;;;;EAIC,WAkBzB,CAAA,EA5MF,YA4ME;EAAU;;;;;;;;;AAzIJ;;;;;;;;;qBAhDH,uBAAuB;;;;;;;;;;WAUjC;;;;;;;;cAQG;;;;;;;;cAQA;;;;;;;;;;;;;;;;;cAmBA,8GAGA,WAAW;;;;;;eAEV;;;;;;;;;;;;;;;;;;mBAoBI;;;;;;;;;sBAUG;;uBAGC;kBAGhB,cAAc,gBACO,cAAc;0BAEC;;;;;;;;;;;;;;;;;;;sBAuDrB,wBAAwB;;kCAGZ,QAAK,gBAAA,oBAAA,uBAAA;mCAIJ,QAAK,gBAAA,oBAAA,wBAAA;kCAIN,QAAK,gBAAA,oBAAA,uBAAA;oCAIH,QAAK,gBAAA,oBAAA,yBAAA;qCAIJ,QAAK,gBAAA,oBAAA,0BAAA;sCAIJ,QAAK,gBAAA,oBAAA,2BAAA;;;;;;;;;;;;;;;kBAkBzB,aAAa,QAAQ,OAAO;;;;;;;;;;;;;;;6BAuBjB,eAAe,QAAQ,OAAO;;;;;;;;;;aAkB9C"}
+{"version":3,"file":"rest-api.d.cts","names":[],"sources":["../src/rest-api.ts"],"mappings":";;;;;;;;;KAkDK,YAAY,wBAAwB;iBAExB,cAIhB;;;;;;;;;;;;EAaA;;;;;;EAMA;;;;;;EAMA;IACC;IACA;IACA;IACA;;;;;;;EAOD,cAAc;;;;;;;;;;;;;;;;;;;EAmBd,mBAAmB,uBAAuB;;;;;;;;;;EAU1C,SAAS;;;;;;;;EAQT,YAAY;;;;;;;;EAQZ,YAAY;;;;;;;;;;;;;;;;;;qBAoBA,QACZ,qCACM,iEACM,WAAW;;mBAuCL;;mBAEA;;mBAEA;WAzCT,IAAI;;;;;;WAOJ;IACR;IACA;IACA;;;;;;;;;WAUQ,QAAQ;;;;;;;;;WAUR,WAAW;;WAGX,YAAY;EAErB,YACC,IAAI,cAAc,QACD,QAAQ,cAAc,eAEtB;;EAAA,wBAAuB,cAEvB;;EAAA,gBAAgB;;WAwEzB,KAAK;WACL,MAAM;WACN,KAAK;WACL,OAAO;WACP,QAAQ;WACR,SAAS;;;;;;;;;;;;;;;;;;;WAoBT,UAAU;WACV,SAAS;WACT,SAAS;WACT,OAAO;WACP,YAAY;WACZ,WAAW;WACX,KAAK;WACL,OAAO;;;;;;;;;;;;;;;;EAiBhB,KAAK,WAAW,gBAAgB,QAAQ,OAAO;;;;;;;;;;;;;;;EAuB/C,MAAM,qBAAqB,eAAe,QAAQ,OAAO;;;;;;;;;;EAkBzD,WAAW"}

package/dist/rest-api.d.mts

@@ -1,37 +1,32 @@
-import "./Construct-Ct8nalEi.mjs";
-import "./index-D3zjrwjr.mjs";
-import { Declarable } from "./construct-interface-g5GM5pwR.mjs";
-import "./types-aKksMEWL.mjs";
-import { BuiltInSecuritySchemeId } from "./Endpoint-Dem2XyCu.mjs";
-import { EndpointBuilder, EndpointFactory, RemoveTrailingSlash } from "./index-DbKmfl-q.mjs";
-import { AppSpec, ConstructName, Declaration, Dependency } from "@geekmidas/manifest";
+import { i as Declarable, t as Authenticator } from "./construct-interface-DluK3_da.mjs";
+import { T as BuiltInSecuritySchemeId } from "./Endpoint-CwM8Rzfs.mjs";
+import { t as EndpointFactory } from "./EndpointFactory-0plFjvb7.mjs";
+import { ConstructName, Declaration, Dependency } from "@geekmidas/manifest";
 import { EnvironmentParser } from "@geekmidas/envkit";
 import { Logger } from "@geekmidas/logger";
 import { Telescope } from "@geekmidas/telescope";
-
 //#region src/rest-api.d.ts
-
-interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
+/** The factory a surface builds its endpoints from. */
+type Endpoints = EndpointFactory<[], '', Logger>;
+export interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
   /**
-   * The app that serves this surface: where its source lives, which globs
-   * find its code, how it is run.
-   *
-   * What makes a surface a deploy unit rather than something a deploy has to
-   * be told about separately: one `RestApi` is one server. A `StaticSite` says
-   * the same thing, and the two are the same kind of statement.
-   *
-   * Normally omitted. One RestApi is one server, always — there is no mode in
-   * which a surface shares somebody else's container, because a surface that
-   * gets its process by inference gets it from whatever happened to reference
-   * it, and that was the thing worth removing.
-   *
-   * So this is an override and nothing else. Everything in it follows from
-   * this construct's id — `apps/<kebab-id>` where that directory exists, the
-   * conventional code directories under it, a port assigned in a stable
-   * order. Write one when the layout genuinely differs:
-   * `app: { path: 'services/api' }`.
+   * The app that serves this surface, relative to the workspace root —
+   * `'apps/api'`, or `'.'` in a single-app project.
+   *
+   * Required. It was inferred from the id (`apps/<kebab-id>`, or the root
+   * when no such directory existed), which meant a surface's home was
+   * whatever happened to be on disk. It is where the app's `package.json`
+   * and base `tsconfig.json` are, and which build serves this surface. It
+   * does not change discovery: constructs still load from the workspace's
+   * `constructs` glob.
    */
-  app?: AppSpec;
+  path: string;
+  /**
+   * The label it answers on under a stage's domain — `api` for
+   * `api.myapp.com`, from `deploy.domains` — and under the project locally,
+   * `api.myapp.localhost`. Absent, its id kebab-cased.
+   */
+  subdomain?: string;
   /**
    * CORS tunables. The *origins* are never here — they are read off the
    * constructs that declared an edge to this surface, which is the whole point
@@ -98,19 +93,21 @@ interface RestApiConfig<TAuthorizers extends readonly string[] = readonly []> {
 /**
  * What is *not* here, and why.
  *
- * `dependsOn`, `database`, `auditor` and `publisher` all inject a capability
+ * `dependsOn`, `database`, `auditor` and `.event(topic, …)` all inject a capability
  * into a handler. Putting one on the surface hands it to every route the
  * surface serves — a health check gets the database because a report needed it
  * — which is the thing least privilege forbids and the reason `.calls()` is not
- * spelled `dependsOn`. They belong to the endpoint, or to a factory branched
- * from `api.endpoints` for a group of endpoints that genuinely share them.
+ * spelled `dependsOn`. They belong to the endpoint, or to a branch —
+ * `api.database(db)` — for a group of endpoints that genuinely share them. A
+ * branch is a new factory; the surface config stays free of grants.
  *
  * `auth` is not here either: `.auth(construct)` already declares it, and a
  * second way to say the same thing is the duplication this whole model removes.
  *
  * What is left is what the *process* is rather than what a route may reach.
  */
-declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
+export declare class RestApi<TName extends string = string, const TAuthorizers extends readonly string[] = readonly []> implements Declarable<TName> {
+  #private;
   private readonly config;
   /** Internal: how `.calls()` carries edges into the copy it returns. */
   private readonly dependencies;
@@ -146,34 +143,44 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
   readonly envParser: EnvironmentParser<{}>;
   /** The Telescope instance, when this surface was given one. */
   readonly telescope?: Telescope;
-  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>, /** Internal: how `.calls()` carries edges into the copy it returns. */
-  dependencies?: readonly Dependency[], /** Internal: how `.auth()` carries the authenticator into its copy. */
-  authenticator?: string | undefined);
+  constructor(id: ConstructName<TName>, config: RestApiConfig<TAuthorizers>,
+  /** Internal: how `.calls()` carries edges into the copy it returns. */
+  dependencies?: readonly Dependency[],
+  /** Internal: how `.auth()` carries the authenticator into its copy. */
+  authenticator?: Authenticator | undefined);
+  /** `api.get('/users')` — one route on this surface. */
+  readonly get: Endpoints['get'];
+  readonly post: Endpoints['post'];
+  readonly put: Endpoints['put'];
+  readonly patch: Endpoints['patch'];
+  readonly delete: Endpoints['delete'];
+  readonly options: Endpoints['options'];
   /**
-   * This surface's endpoint factory.
-   *
-   * `api.get('/users')` is the short form and covers most routes. Reach for
-   * this one when a *group* of endpoints shares something a single route would
-   * otherwise repeat — a database, an auditor, a publisher:
+   * A branch for a *group* of endpoints that shares what a single route would
+   * otherwise repeat — a database, an auditor, a publisher, a session:
    *
    * ```ts
-   * const audited = api.endpoints.database(db).auditor(AuditStore);
-   * export const createUser = audited.post('/users').handle(...);
+   * export const router = api.database(database);
+   * export const createUser = router.post('/users').handle(({ db }) => …);
    * ```
    *
-   * A factory branched from here keeps the surface, so its endpoints still
-   * know which API serves them. That is deliberately narrower than putting the
-   * same thing in the surface's own config: a group opts in, where a surface
-   * would grant it to every route it serves.
+   * Each returns a new factory and leaves the surface as it was. That is the
+   * whole difference from putting the same thing in the surface's config: a
+   * group opts in, where the surface would grant it to every route it serves —
+   * a health check handed the database because a profile endpoint needed it.
+   *
+   * `dependsOn` is deliberately not here. It is per endpoint, and on the
+   * surface it would read as the API depending on something, which is what
+   * `.calls()` and `.auth()` say instead.
    */
-  readonly endpoints: EndpointFactory<[], '', Logger>;
-  /** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */
-  get<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "GET", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
-  post<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "POST", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
-  put<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PUT", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
-  patch<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "PATCH", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
-  delete<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "DELETE", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
-  options<TPath extends string>(path: TPath): EndpointBuilder<RemoveTrailingSlash<TPath>, "OPTIONS", {}, [], Logger, undefined, unknown, undefined, string, readonly string[], undefined, string, ExtractStorageAuditAction<NonNullable<TAuditStorage>>, undefined, string>;
+  readonly database: Endpoints['database'];
+  readonly session: Endpoints['session'];
+  readonly auditor: Endpoints['auditor'];
+  readonly actor: Endpoints['actor'];
+  readonly authorizer: Endpoints['authorizer'];
+  readonly authorize: Endpoints['authorize'];
+  readonly rls: Endpoints['rls'];
+  readonly route: Endpoints['route'];
   /**
    * What authenticates this surface.
    *
@@ -183,12 +190,13 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    * what a request is allowed to be. A surface with two of the first is a
    * mistake; two of the second is Tuesday.
    *
-   * It records the id, not a client. Every endpoint consumes the same thing —
-   * `verify(request) → Session | null` — and that is what every provider
-   * shares, whether the server is mounted in this process, deployed beside it,
-   * or an OIDC issuer somebody else runs.
+   * It declares the id, and keeps the construct: a session callback reads from
+   * it as `auth` — `session(async ({ auth }) => auth.getSession())` — which
+   * calls the construct's `verify(headers)`. That is the one thing every
+   * provider shares, whether the server is mounted in this process, deployed
+   * beside it, or an OIDC issuer somebody else runs.
    */
-  auth(construct: Declarable): RestApi<TName, TAuthorizers>;
+  auth(construct: Authenticator): RestApi<TName, TAuthorizers>;
   /**
    * Other surfaces this one calls.
    *
@@ -215,7 +223,6 @@ declare class RestApi<TName extends string = string, const TAuthorizers extends
    */
   declare(): Declaration[];
 }
-//# sourceMappingURL=rest-api.d.ts.map
 //#endregion
-export { RestApi, RestApiConfig };
+export type { Authenticator };
 //# sourceMappingURL=rest-api.d.mts.map

package/dist/rest-api.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.d.mts","names":[],"sources":["../src/rest-api.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AA2LoB,UAnJH,aAmJG,CAAA,qBAAA,SAAA,MAAA,EAAA,GAAA,SAAA,EAAA,CAAA,CAAA;EAAK;;;;;;;;;;;;;;;;;;;EAiEc,GAAA,CAAA,EA3LhC,OA2LgC;EAAA;;;;;EAID,IAAA,CAAA,EAAA;IAAA,MAAA,CAAA,EAAA,MAAA;IAAA,WAAA,CAAA,EAAA,OAAA;IAAA,YAAA,CAAA,EAAA,SAAA,MAAA,EAAA;IAAA,aAAA,CAAA,EAAA,SAAA,MAAA,EAAA;EAAA,CAAA;EAIE;;;;;EAAA,WAAA,CAAA,EAlLzB,YAkLyB;EAAA;;;;;;;;;;;;;;;;;;EA0Bb,iBAAW,EAzLlB,YAyLkB,CAAA,MAAA,CAAA,GAzLK,uBAyLL,GAAA,MAAA;EAAK;;;;;;;;AAzIpB;WAtCb;;;;;;;;cAQG;;;;;;;;cAQA;;;;;;;;;;;;;;;;;cAmBA,8GAGA,WAAW;;;;;;eAEV;;;;;;;;;;;;;;;;;;mBAoBI;;;;;;;;;sBAUG;;uBAGC;kBAGhB,cAAc,gBACO,cAAc;0BAEC;;;;;;;;;;;;;;;;;;;sBAuDrB,wBAAwB;;kCAGZ,QAAK,gBAAA,oBAAA,uBAAA,qFAAA,0BAAA,YAAA;mCAIJ,QAAK,gBAAA,oBAAA,wBAAA,qFAAA,0BAAA,YAAA;kCAIN,QAAK,gBAAA,oBAAA,uBAAA,qFAAA,0BAAA,YAAA;oCAIH,QAAK,gBAAA,oBAAA,yBAAA,qFAAA,0BAAA,YAAA;qCAIJ,QAAK,gBAAA,oBAAA,0BAAA,qFAAA,0BAAA,YAAA;sCAIJ,QAAK,gBAAA,oBAAA,2BAAA,qFAAA,0BAAA,YAAA;;;;;;;;;;;;;;;kBAkBzB,aAAa,QAAQ,OAAO;;;;;;;;;;;;;;;6BAuBjB,eAAe,QAAQ,OAAO;;;;;;;;;;aAkB9C"}
+{"version":3,"file":"rest-api.d.mts","names":[],"sources":["../src/rest-api.ts"],"mappings":";;;;;;;;;KAkDK,YAAY,wBAAwB;iBAExB,cAIhB;;;;;;;;;;;;EAaA;;;;;;EAMA;;;;;;EAMA;IACC;IACA;IACA;IACA;;;;;;;EAOD,cAAc;;;;;;;;;;;;;;;;;;;EAmBd,mBAAmB,uBAAuB;;;;;;;;;;EAU1C,SAAS;;;;;;;;EAQT,YAAY;;;;;;;;EAQZ,YAAY;;;;;;;;;;;;;;;;;;qBAoBA,QACZ,qCACM,iEACM,WAAW;;mBAuCL;;mBAEA;;mBAEA;WAzCT,IAAI;;;;;;WAOJ;IACR;IACA;IACA;;;;;;;;;WAUQ,QAAQ;;;;;;;;;WAUR,WAAW;;WAGX,YAAY;EAErB,YACC,IAAI,cAAc,QACD,QAAQ,cAAc,eAEtB;;EAAA,wBAAuB,cAEvB;;EAAA,gBAAgB;;WAwEzB,KAAK;WACL,MAAM;WACN,KAAK;WACL,OAAO;WACP,QAAQ;WACR,SAAS;;;;;;;;;;;;;;;;;;;WAoBT,UAAU;WACV,SAAS;WACT,SAAS;WACT,OAAO;WACP,YAAY;WACZ,WAAW;WACX,KAAK;WACL,OAAO;;;;;;;;;;;;;;;;EAiBhB,KAAK,WAAW,gBAAgB,QAAQ,OAAO;;;;;;;;;;;;;;;EAuB/C,MAAM,qBAAqB,eAAe,QAAQ,OAAO;;;;;;;;;;EAkBzD,WAAW"}

package/dist/rest-api.mjs

@@ -1,23 +1,19 @@
-import "./Construct-BD5neF7w.mjs";
-import { edgeTo } from "./construct-interface-Z4CpS8tK.mjs";
-import "./functions-Ck21Uyq0.mjs";
-import { EndpointFactory } from "./EndpointFactory-b4ituq-s.mjs";
-import "./clone-DblgEZZa.mjs";
-import "./Endpoint-Dij_wOcc.mjs";
-import { envParserFor } from "./surfaceEnv-C3Ktahea.mjs";
+import { edgeTo } from "./construct-interface.mjs";
+import { o as getSecurityScheme, t as EndpointFactory } from "./EndpointFactory-DR1rebok.mjs";
+import { n as envParserFor } from "./surfaceEnv-wMT5QzgZ.mjs";
 import { canonicalId, provideKey } from "@geekmidas/manifest";
 import { DEFAULT_LOGGER } from "@geekmidas/logger/console";
-
 //#region src/rest-api.ts
 /**
 * What is *not* here, and why.
 *
-* `dependsOn`, `database`, `auditor` and `publisher` all inject a capability
+* `dependsOn`, `database`, `auditor` and `.event(topic, …)` all inject a capability
 * into a handler. Putting one on the surface hands it to every route the
 * surface serves — a health check gets the database because a report needed it
 * — which is the thing least privilege forbids and the reason `.calls()` is not
-* spelled `dependsOn`. They belong to the endpoint, or to a factory branched
-* from `api.endpoints` for a group of endpoints that genuinely share them.
+* spelled `dependsOn`. They belong to the endpoint, or to a branch —
+* `api.database(db)` — for a group of endpoints that genuinely share them. A
+* branch is a new factory; the surface config stays free of grants.
 *
 * `auth` is not here either: `.auth(construct)` already declares it, and a
 * second way to say the same thing is the duplication this whole model removes.
@@ -25,6 +21,9 @@ import { DEFAULT_LOGGER } from "@geekmidas/logger/console";
 * What is left is what the *process* is rather than what a route may reach.
 */
 var RestApi = class RestApi {
+	config;
+	dependencies;
+	authenticator;
 	id;
 	/**
 	* Declared once and read by both `declare()` and anything that consumes this
@@ -68,53 +67,79 @@ var RestApi = class RestApi {
 			id: canonical,
 			envParser: config.envParser
 		} : void 0);
-		this.endpoints = new EndpointFactory({
+		this.#endpoints = new EndpointFactory({
 			defaultLogger: this.logger,
-			...config.authorizers ? { availableAuthorizers: config.authorizers.map((name) => ({ name })) } : {},
+			...config.authorizers ? { availableAuthorizers: config.authorizers.map((name) => {
+				const securityScheme = getSecurityScheme(name);
+				return securityScheme ? {
+					name,
+					securityScheme
+				} : { name };
+			}) } : {},
 			...config.defaultAuthorizer && config.defaultAuthorizer !== "none" ? { defaultAuthorizerName: config.defaultAuthorizer } : {},
 			surface: {
 				id: this.id,
-				envParser: this.envParser
+				envParser: this.envParser,
+				...authenticator ? { auth: authenticator } : {}
 			}
 		});
+		const endpoints = this.#endpoints;
+		this.get = endpoints.get.bind(endpoints);
+		this.post = endpoints.post.bind(endpoints);
+		this.put = endpoints.put.bind(endpoints);
+		this.patch = endpoints.patch.bind(endpoints);
+		this.delete = endpoints.delete.bind(endpoints);
+		this.options = endpoints.options.bind(endpoints);
+		this.database = endpoints.database.bind(endpoints);
+		this.session = endpoints.session.bind(endpoints);
+		this.auditor = endpoints.auditor.bind(endpoints);
+		this.actor = endpoints.actor.bind(endpoints);
+		this.authorizer = endpoints.authorizer.bind(endpoints);
+		this.authorize = endpoints.authorize.bind(endpoints);
+		this.rls = endpoints.rls.bind(endpoints);
+		this.route = endpoints.route.bind(endpoints);
 	}
 	/**
-	* This surface's endpoint factory.
+	* This surface's endpoint factory, which every method below starts from.
 	*
-	* `api.get('/users')` is the short form and covers most routes. Reach for
-	* this one when a *group* of endpoints shares something a single route would
-	* otherwise repeat — a database, an auditor, a publisher:
+	* Private: a surface *is* where endpoints are built, so there is no second
+	* object to reach through first. `api.database(db)` said the same
+	* thing as `api.database(db)` with one more word to learn.
+	*/
+	#endpoints;
+	/** `api.get('/users')` — one route on this surface. */
+	get;
+	post;
+	put;
+	patch;
+	delete;
+	options;
+	/**
+	* A branch for a *group* of endpoints that shares what a single route would
+	* otherwise repeat — a database, an auditor, a publisher, a session:
 	*
 	* ```ts
-	* const audited = api.endpoints.database(db).auditor(AuditStore);
-	* export const createUser = audited.post('/users').handle(...);
+	* export const router = api.database(database);
+	* export const createUser = router.post('/users').handle(({ db }) => …);
 	* ```
 	*
-	* A factory branched from here keeps the surface, so its endpoints still
-	* know which API serves them. That is deliberately narrower than putting the
-	* same thing in the surface's own config: a group opts in, where a surface
-	* would grant it to every route it serves.
+	* Each returns a new factory and leaves the surface as it was. That is the
+	* whole difference from putting the same thing in the surface's config: a
+	* group opts in, where the surface would grant it to every route it serves —
+	* a health check handed the database because a profile endpoint needed it.
+	*
+	* `dependsOn` is deliberately not here. It is per endpoint, and on the
+	* surface it would read as the API depending on something, which is what
+	* `.calls()` and `.auth()` say instead.
 	*/
-	endpoints;
-	/** `api.get('/users')` — sugar for `api.endpoints.get('/users')`. */
-	get(path) {
-		return this.endpoints.get(path);
-	}
-	post(path) {
-		return this.endpoints.post(path);
-	}
-	put(path) {
-		return this.endpoints.put(path);
-	}
-	patch(path) {
-		return this.endpoints.patch(path);
-	}
-	delete(path) {
-		return this.endpoints.delete(path);
-	}
-	options(path) {
-		return this.endpoints.options(path);
-	}
+	database;
+	session;
+	auditor;
+	actor;
+	authorizer;
+	authorize;
+	rls;
+	route;
 	/**
 	* What authenticates this surface.
 	*
@@ -124,13 +149,14 @@ var RestApi = class RestApi {
 	* what a request is allowed to be. A surface with two of the first is a
 	* mistake; two of the second is Tuesday.
 	*
-	* It records the id, not a client. Every endpoint consumes the same thing —
-	* `verify(request) → Session | null` — and that is what every provider
-	* shares, whether the server is mounted in this process, deployed beside it,
-	* or an OIDC issuer somebody else runs.
+	* It declares the id, and keeps the construct: a session callback reads from
+	* it as `auth` — `session(async ({ auth }) => auth.getSession())` — which
+	* calls the construct's `verify(headers)`. That is the one thing every
+	* provider shares, whether the server is mounted in this process, deployed
+	* beside it, or an OIDC issuer somebody else runs.
 	*/
 	auth(construct) {
-		return new RestApi(this.id, this.config, [...this.dependencies, edgeTo(construct)], construct.id);
+		return new RestApi(this.id, this.config, [...this.dependencies, edgeTo(construct)], construct);
 	}
 	/**
 	* Other surfaces this one calls.
@@ -162,12 +188,11 @@ var RestApi = class RestApi {
 		return [{
 			kind: "rest-api",
 			id: this.id,
-			app: {
-				...this.config.app,
-				...this.config.telescope ? { telescope: true } : {}
-			},
+			path: this.config.path,
+			...this.config.subdomain ? { subdomain: this.config.subdomain } : {},
+			...this.config.telescope ? { telescope: true } : {},
 			...this.config.cors ? { cors: this.config.cors } : {},
-			...this.authenticator ? { auth: this.authenticator } : {},
+			...this.authenticator ? { auth: this.authenticator.id } : {},
 			endpoints: [],
 			...this.dependencies.length ? { calls: this.dependencies } : {},
 			...this.config.authorizers?.length ? { authorizers: this.config.authorizers } : {},
@@ -180,7 +205,7 @@ var RestApi = class RestApi {
 		}];
 	}
 };
-
 //#endregion
 export { RestApi };
+
 //# sourceMappingURL=rest-api.mjs.map