@geekmidas/constructs 10.0.0-alpha.12 → 10.0.0-alpha.121

package/dist/endpoints/index.d.cts

@@ -1,7 +1,105 @@
-import "../Construct-C0ijr2qp.cjs";
-import "../index-D24Xm79M.cjs";
-import "../construct-interface-D9d4Gm4p.cjs";
-import "../types-BlAkSuGI.cjs";
-import { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointContext, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme } from "../Endpoint-dav89W6-.cjs";
-import { EndpointBuilder, EndpointFactory, createApiGatewayCookies, createApiGatewayHeaders, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, publishConstructEvents } from "../index-Bd5FqCoe.cjs";
-export { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointBuilder, EndpointContext, EndpointFactory, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+import { s as publishConstructEvents } from "../Construct-CFW0zjdD.cjs";
+import { A as SecurityScheme, C as ActorExtractor, D as BuiltInSecuritySchemeId, E as BUILT_IN_SECURITY_SCHEMES, M as getSecurityScheme, N as isBuiltInSecurityScheme, O as OAuthFlow, S as RlsContextExtractor, T as Authorizer, _ as SessionAuth, a as EndpointContext, b as RlsConfig, c as EndpointSchemas, d as HeaderFn, f as RedirectStatus, g as NoAuthenticator, h as SuccessStatus, i as Endpoint, j as createAuthorizer, k as OAuthFlows, l as EndpointStatus, n as ConvertRouteParams, o as EndpointHandler, p as ResponseBuilder, r as CookieFn, s as EndpointOutput, u as EndpointSurface, v as RLS_BYPASS, w as MappedAudit, x as RlsContext, y as RlsBypass } from "../Endpoint-DgrpG15P.cjs";
+import { a as UPLOAD_POST_SCHEMA, c as UploadContentTypeUnresolved, d as UploadOptions, f as UploadPost, i as UploadHandler, l as UploadExpiryInvalid, n as EndpointBuilder, o as UploadAcceptInvalid, r as UploadEndpointBuilder, s as UploadContentTypeRefused, t as EndpointFactory, u as UploadMaxSizeInvalid } from "../EndpointFactory-Cc863XJS.cjs";
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { Context } from "hono";
+import { HttpError } from "@geekmidas/errors";
+//#region src/endpoints/lazyAccessors.d.ts
+/**
+ * Create a lazy header accessor for Hono.
+ * Uses `c.req.header(name)` for single lookups (native, case-insensitive).
+ * Only calls `c.req.header()` to get all headers when needed.
+ */
+export declare function createHonoHeaders(c: Context): HeaderFn;
+/**
+ * Create a lazy cookie accessor for Hono.
+ * Uses `getCookie(c, name)` for single lookups (native).
+ * Only parses the cookie header when all cookies are requested.
+ */
+export declare function createHonoCookies(c: Context): CookieFn;
+/**
+ * Create a lazy header accessor for API Gateway events.
+ * Handles case-insensitive lookups.
+ */
+export declare function createApiGatewayHeaders(headers: Record<string, string | undefined> | null | undefined): HeaderFn;
+/**
+ * Create a lazy cookie accessor for API Gateway events.
+ * Decodes URL-encoded values to match browser behavior.
+ */
+export declare function createApiGatewayCookies(cookies: string[] | undefined, cookieHeader: string | undefined): CookieFn;
+/**
+ * Create a no-op header accessor (for minimal endpoints that don't use headers).
+ */
+export declare function createNoopHeaders(): HeaderFn;
+/**
+ * Create a no-op cookie accessor (for minimal endpoints that don't use cookies).
+ */
+export declare function createNoopCookies(): CookieFn;
+//#endregion
+//#region src/endpoints/readRequestBody.d.ts
+/**
+ * The media types an endpoint's `.body()` schema can be handed — as written
+ * in the 415 a request in any other type is answered with.
+ */
+export declare const SUPPORTED_BODY_TYPES: readonly ['application/json', 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/*'];
+/**
+ * A request whose body is in a media type no endpoint reads — XML, a bare
+ * octet stream. Answered with a 415, before the body schema runs.
+ */
+export declare class UnsupportedRequestContentType extends HttpError {
+  readonly contentType: string;
+  constructor(contentType: string);
+}
+/**
+ * A body that says it is JSON and is not. Answered with a 400 — the request
+ * is broken, not merely invalid against the schema.
+ */
+export declare class MalformedRequestBody extends HttpError {
+  readonly contentType: string;
+  constructor(contentType: string, cause?: Error);
+}
+/**
+ * What a body is read from: a `Request`, or Hono's request — which caches
+ * what it read, so a later reader is not handed a spent stream.
+ */
+interface RequestBodySource {
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+  formData(): Promise<FormData>;
+}
+interface ReadRequestBodyOptions {
+  /**
+   * A body with no Content-Type: read as JSON (`'json'`, what API Gateway
+   * has always done), or not read at all and handed to the schema as `{}`
+   * (`'empty'`, what a Hono server has always done).
+   */
+  untyped: 'json' | 'empty';
+}
+/**
+ * A request body, read by its Content-Type into what an endpoint's `.body()`
+ * schema validates — the one place every adaptor reads a body:
+ *
+ * - `application/json` (and `application/*+json`) — the parsed JSON.
+ * - `application/x-www-form-urlencoded` and `multipart/form-data` — a plain
+ *   object of fields, as an HTML form posts them. A repeated field, or one
+ *   named `field[]`, is an array; a file part is a `File`.
+ * - `text/*` — the text.
+ *
+ * Anything else is an {@link UnsupportedRequestContentType}.
+ */
+export declare function readRequestBody(source: RequestBodySource, contentType: string | null | undefined, options: ReadRequestBodyOptions): Promise<unknown>;
+//#endregion
+//#region src/endpoints/surfaceEnv.d.ts
+/**
+ * The default parser, built once.
+ *
+ * Once because `Credentials` resolves through `globalThis` and decryption is
+ * not free, and because two parsers over the same environment are two caches of
+ * the same answer.
+ */
+export declare function defaultEnvParser(): EnvironmentParser<{}>;
+/** The parser for an endpoint, from its surface or the default. */
+export declare function envParserFor(surface: EndpointSurface | undefined): EnvironmentParser<{}>;
+//#endregion
+export { type ActorExtractor, type Authorizer, BUILT_IN_SECURITY_SCHEMES, type BuiltInSecuritySchemeId, type ConvertRouteParams, Endpoint, EndpointBuilder, type EndpointContext, EndpointFactory, type EndpointHandler, type EndpointOutput, type EndpointSchemas, type EndpointStatus, type MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, RedirectStatus, type RequestBodySource, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, SuccessStatus, UPLOAD_POST_SCHEMA, UploadAcceptInvalid, UploadContentTypeRefused, UploadContentTypeUnresolved, UploadEndpointBuilder, UploadExpiryInvalid, type UploadHandler, UploadMaxSizeInvalid, type UploadOptions, type UploadPost, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+//# sourceMappingURL=index.d.cts.map

package/dist/endpoints/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/endpoints/lazyAccessors.ts","../../src/endpoints/readRequestBody.ts","../../src/endpoints/surfaceEnv.ts"],"mappings":";;;;;;;;;;;;wBAgBgB,kBAAkB,GAAG,UAAU;;;;;;wBAqB/B,kBAAkB,GAAG,UAAU;;;;;wBAgC/B,wBACf,SAAS,wDACP;;;;;wBAoCa,wBACf,+BACA,mCACE;;;;wBAmHa,qBAAqB;;;;wBAUrB,qBAAqB;;;;;;;qBCrOxB;;;;;qBAWA,sCAAsC;WAC7B;EAArB,YAAqB;;;;;;qBAiBT,6BAA6B;WAE/B;EADV,YACU,qBACT,QAAQ;;;;;;UAeO;EAChB,QAAQ;EACR,QAAQ;EACR,YAAY,QAAQ;;UAGJ;;;;;;EAMhB;;;;;;;;;;;;;;wBAeqB,gBACrB,QAAQ,mBACR,wCACA,SAAS,yBACP;;;;;;;;;;wBCnDa,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}

package/dist/endpoints/index.d.mts

@@ -1,7 +1,105 @@
-import "../Construct-Ct8nalEi.mjs";
-import "../index-_ajboYxK.mjs";
-import "../construct-interface-g5GM5pwR.mjs";
-import "../types-aKksMEWL.mjs";
-import { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointContext, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme } from "../Endpoint-BjWKinFA.mjs";
-import { EndpointBuilder, EndpointFactory, createApiGatewayCookies, createApiGatewayHeaders, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, publishConstructEvents } from "../index-lAO9egTb.mjs";
-export { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointBuilder, EndpointContext, EndpointFactory, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+import { s as publishConstructEvents } from "../Construct-B7AXn0xH.mjs";
+import { A as SecurityScheme, C as ActorExtractor, D as BuiltInSecuritySchemeId, E as BUILT_IN_SECURITY_SCHEMES, M as getSecurityScheme, N as isBuiltInSecurityScheme, O as OAuthFlow, S as RlsContextExtractor, T as Authorizer, _ as SessionAuth, a as EndpointContext, b as RlsConfig, c as EndpointSchemas, d as HeaderFn, f as RedirectStatus, g as NoAuthenticator, h as SuccessStatus, i as Endpoint, j as createAuthorizer, k as OAuthFlows, l as EndpointStatus, n as ConvertRouteParams, o as EndpointHandler, p as ResponseBuilder, r as CookieFn, s as EndpointOutput, u as EndpointSurface, v as RLS_BYPASS, w as MappedAudit, x as RlsContext, y as RlsBypass } from "../Endpoint-CeFkSwh5.mjs";
+import { a as UPLOAD_POST_SCHEMA, c as UploadContentTypeUnresolved, d as UploadOptions, f as UploadPost, i as UploadHandler, l as UploadExpiryInvalid, n as EndpointBuilder, o as UploadAcceptInvalid, r as UploadEndpointBuilder, s as UploadContentTypeRefused, t as EndpointFactory, u as UploadMaxSizeInvalid } from "../EndpointFactory-Dbw9ugkX.mjs";
+import { HttpError } from "@geekmidas/errors";
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { Context } from "hono";
+//#region src/endpoints/lazyAccessors.d.ts
+/**
+ * Create a lazy header accessor for Hono.
+ * Uses `c.req.header(name)` for single lookups (native, case-insensitive).
+ * Only calls `c.req.header()` to get all headers when needed.
+ */
+export declare function createHonoHeaders(c: Context): HeaderFn;
+/**
+ * Create a lazy cookie accessor for Hono.
+ * Uses `getCookie(c, name)` for single lookups (native).
+ * Only parses the cookie header when all cookies are requested.
+ */
+export declare function createHonoCookies(c: Context): CookieFn;
+/**
+ * Create a lazy header accessor for API Gateway events.
+ * Handles case-insensitive lookups.
+ */
+export declare function createApiGatewayHeaders(headers: Record<string, string | undefined> | null | undefined): HeaderFn;
+/**
+ * Create a lazy cookie accessor for API Gateway events.
+ * Decodes URL-encoded values to match browser behavior.
+ */
+export declare function createApiGatewayCookies(cookies: string[] | undefined, cookieHeader: string | undefined): CookieFn;
+/**
+ * Create a no-op header accessor (for minimal endpoints that don't use headers).
+ */
+export declare function createNoopHeaders(): HeaderFn;
+/**
+ * Create a no-op cookie accessor (for minimal endpoints that don't use cookies).
+ */
+export declare function createNoopCookies(): CookieFn;
+//#endregion
+//#region src/endpoints/readRequestBody.d.ts
+/**
+ * The media types an endpoint's `.body()` schema can be handed — as written
+ * in the 415 a request in any other type is answered with.
+ */
+export declare const SUPPORTED_BODY_TYPES: readonly ['application/json', 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/*'];
+/**
+ * A request whose body is in a media type no endpoint reads — XML, a bare
+ * octet stream. Answered with a 415, before the body schema runs.
+ */
+export declare class UnsupportedRequestContentType extends HttpError {
+  readonly contentType: string;
+  constructor(contentType: string);
+}
+/**
+ * A body that says it is JSON and is not. Answered with a 400 — the request
+ * is broken, not merely invalid against the schema.
+ */
+export declare class MalformedRequestBody extends HttpError {
+  readonly contentType: string;
+  constructor(contentType: string, cause?: Error);
+}
+/**
+ * What a body is read from: a `Request`, or Hono's request — which caches
+ * what it read, so a later reader is not handed a spent stream.
+ */
+interface RequestBodySource {
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+  formData(): Promise<FormData>;
+}
+interface ReadRequestBodyOptions {
+  /**
+   * A body with no Content-Type: read as JSON (`'json'`, what API Gateway
+   * has always done), or not read at all and handed to the schema as `{}`
+   * (`'empty'`, what a Hono server has always done).
+   */
+  untyped: 'json' | 'empty';
+}
+/**
+ * A request body, read by its Content-Type into what an endpoint's `.body()`
+ * schema validates — the one place every adaptor reads a body:
+ *
+ * - `application/json` (and `application/*+json`) — the parsed JSON.
+ * - `application/x-www-form-urlencoded` and `multipart/form-data` — a plain
+ *   object of fields, as an HTML form posts them. A repeated field, or one
+ *   named `field[]`, is an array; a file part is a `File`.
+ * - `text/*` — the text.
+ *
+ * Anything else is an {@link UnsupportedRequestContentType}.
+ */
+export declare function readRequestBody(source: RequestBodySource, contentType: string | null | undefined, options: ReadRequestBodyOptions): Promise<unknown>;
+//#endregion
+//#region src/endpoints/surfaceEnv.d.ts
+/**
+ * The default parser, built once.
+ *
+ * Once because `Credentials` resolves through `globalThis` and decryption is
+ * not free, and because two parsers over the same environment are two caches of
+ * the same answer.
+ */
+export declare function defaultEnvParser(): EnvironmentParser<{}>;
+/** The parser for an endpoint, from its surface or the default. */
+export declare function envParserFor(surface: EndpointSurface | undefined): EnvironmentParser<{}>;
+//#endregion
+export { type ActorExtractor, type Authorizer, BUILT_IN_SECURITY_SCHEMES, type BuiltInSecuritySchemeId, type ConvertRouteParams, Endpoint, EndpointBuilder, type EndpointContext, EndpointFactory, type EndpointHandler, type EndpointOutput, type EndpointSchemas, type EndpointStatus, type MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, RedirectStatus, type RequestBodySource, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, SuccessStatus, UPLOAD_POST_SCHEMA, UploadAcceptInvalid, UploadContentTypeRefused, UploadContentTypeUnresolved, UploadEndpointBuilder, UploadExpiryInvalid, type UploadHandler, UploadMaxSizeInvalid, type UploadOptions, type UploadPost, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+//# sourceMappingURL=index.d.mts.map

package/dist/endpoints/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/endpoints/lazyAccessors.ts","../../src/endpoints/readRequestBody.ts","../../src/endpoints/surfaceEnv.ts"],"mappings":";;;;;;;;;;;;wBAgBgB,kBAAkB,GAAG,UAAU;;;;;;wBAqB/B,kBAAkB,GAAG,UAAU;;;;;wBAgC/B,wBACf,SAAS,wDACP;;;;;wBAoCa,wBACf,+BACA,mCACE;;;;wBAmHa,qBAAqB;;;;wBAUrB,qBAAqB;;;;;;;qBCrOxB;;;;;qBAWA,sCAAsC;WAC7B;EAArB,YAAqB;;;;;;qBAiBT,6BAA6B;WAE/B;EADV,YACU,qBACT,QAAQ;;;;;;UAeO;EAChB,QAAQ;EACR,QAAQ;EACR,YAAY,QAAQ;;UAGJ;;;;;;EAMhB;;;;;;;;;;;;;;wBAeqB,gBACrB,QAAQ,mBACR,wCACA,SAAS,yBACP;;;;;;;;;;wBCnDa,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}

package/dist/endpoints/index.mjs

@@ -1,10 +1,6 @@
-import "../Construct-BD5neF7w.mjs";
-import "../construct-interface-Z4CpS8tK.mjs";
-import "../functions-14lpEFL4.mjs";
-import { BUILT_IN_SECURITY_SCHEMES, EndpointBuilder, EndpointFactory, RLS_BYPASS, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme } from "../EndpointFactory-CjV8F_lJ.mjs";
-import "../clone-DblgEZZa.mjs";
-import { Endpoint, ResponseBuilder } from "../Endpoint-DCQPMdUX.mjs";
-import { defaultEnvParser, envParserFor } from "../surfaceEnv-C3Ktahea.mjs";
-import { createApiGatewayCookies, createApiGatewayHeaders, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, publishConstructEvents } from "../lazyAccessors-BoJN3SMd.mjs";
-
-export { BUILT_IN_SECURITY_SCHEMES, Endpoint, EndpointBuilder, EndpointFactory, RLS_BYPASS, ResponseBuilder, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+import { a as UploadAcceptInvalid, c as UploadExpiryInvalid, d as BUILT_IN_SECURITY_SCHEMES, f as createAuthorizer, i as UPLOAD_POST_SCHEMA, l as UploadMaxSizeInvalid, m as isBuiltInSecurityScheme, n as EndpointBuilder, o as UploadContentTypeRefused, p as getSecurityScheme, r as UploadEndpointBuilder, s as UploadContentTypeUnresolved, t as EndpointFactory, u as RLS_BYPASS } from "../EndpointFactory-c2ZugGig.mjs";
+import { i as publishConstructEvents } from "../functions-CTI-hDem.mjs";
+import { a as NoAuthenticator, i as SuccessStatus, n as RedirectStatus, r as ResponseBuilder, t as Endpoint } from "../Endpoint-gPXhHKhJ.mjs";
+import { n as envParserFor, t as defaultEnvParser } from "../surfaceEnv-wMT5QzgZ.mjs";
+import { a as createApiGatewayCookies, c as createHonoCookies, d as createNoopHeaders, i as readRequestBody, l as createHonoHeaders, n as SUPPORTED_BODY_TYPES, o as createApiGatewayHeaders, r as UnsupportedRequestContentType, t as MalformedRequestBody, u as createNoopCookies } from "../readRequestBody-BTIl3k-D.mjs";
+export { BUILT_IN_SECURITY_SCHEMES, Endpoint, EndpointBuilder, EndpointFactory, MalformedRequestBody, NoAuthenticator, RLS_BYPASS, RedirectStatus, ResponseBuilder, SUPPORTED_BODY_TYPES, SuccessStatus, UPLOAD_POST_SCHEMA, UnsupportedRequestContentType, UploadAcceptInvalid, UploadContentTypeRefused, UploadContentTypeUnresolved, UploadEndpointBuilder, UploadExpiryInvalid, UploadMaxSizeInvalid, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents, readRequestBody };

package/dist/expire-C586zznE.d.cts

@@ -0,0 +1,38 @@
+//#region src/expire.d.ts
+/**
+ * How long a bucket keeps the objects under a prefix.
+ *
+ * Shared by `ObjectStorage` and the bucket a `FileServer` vends, because it is
+ * a fact about the bucket rather than about who serves it: a prefix of
+ * generated files that nobody reads back grows for ever unless the bucket
+ * itself is told to drop them.
+ *
+ * ```ts
+ * new ObjectStorage('Private', { expire: { 'quotes/': { days: 30 } } });
+ * ```
+ *
+ * Whole days, because that is the unit S3's lifecycle — and MinIO's — counts
+ * in. Prefixes are literal: a lifecycle rule matches the start of a key and
+ * has no globs, so a pattern that looks like one is refused rather than
+ * silently matching nothing.
+ */
+type ObjectExpiry = Readonly<Record<string, {
+  readonly days: number;
+}>>;
+/** An expiry prefix the bucket could not match the way it reads. */
+declare class ExpiryPrefixInvalid extends Error {
+  readonly bucket: string;
+  readonly prefix: string;
+  readonly reason: string;
+  constructor(bucket: string, prefix: string, reason: string);
+}
+/** An expiry that is not a whole number of days, one or more. */
+declare class ExpiryDaysInvalid extends Error {
+  readonly bucket: string;
+  readonly prefix: string;
+  readonly days: unknown;
+  constructor(bucket: string, prefix: string, days: unknown);
+}
+//#endregion
+export { ExpiryPrefixInvalid as n, ObjectExpiry as r, ExpiryDaysInvalid as t };
+//# sourceMappingURL=expire-C586zznE.d.cts.map

package/dist/expire-C586zznE.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expire-C586zznE.d.cts","names":[],"sources":["../src/expire.ts"],"mappings":";;;;;;;;;;;;;;;;;;KAiBY,eAAe,SAAS;WAA0B;;;cAGjD,4BAA4B;WAE9B;WACA;WACA;EAHV,YACU,gBACA,gBACA;;;cAWE,0BAA0B;WAE5B;WACA;WACA;EAHV,YACU,gBACA,gBACA"}

package/dist/expire-C586zznE.d.mts

@@ -0,0 +1,38 @@
+//#region src/expire.d.ts
+/**
+ * How long a bucket keeps the objects under a prefix.
+ *
+ * Shared by `ObjectStorage` and the bucket a `FileServer` vends, because it is
+ * a fact about the bucket rather than about who serves it: a prefix of
+ * generated files that nobody reads back grows for ever unless the bucket
+ * itself is told to drop them.
+ *
+ * ```ts
+ * new ObjectStorage('Private', { expire: { 'quotes/': { days: 30 } } });
+ * ```
+ *
+ * Whole days, because that is the unit S3's lifecycle — and MinIO's — counts
+ * in. Prefixes are literal: a lifecycle rule matches the start of a key and
+ * has no globs, so a pattern that looks like one is refused rather than
+ * silently matching nothing.
+ */
+type ObjectExpiry = Readonly<Record<string, {
+  readonly days: number;
+}>>;
+/** An expiry prefix the bucket could not match the way it reads. */
+declare class ExpiryPrefixInvalid extends Error {
+  readonly bucket: string;
+  readonly prefix: string;
+  readonly reason: string;
+  constructor(bucket: string, prefix: string, reason: string);
+}
+/** An expiry that is not a whole number of days, one or more. */
+declare class ExpiryDaysInvalid extends Error {
+  readonly bucket: string;
+  readonly prefix: string;
+  readonly days: unknown;
+  constructor(bucket: string, prefix: string, days: unknown);
+}
+//#endregion
+export { ExpiryPrefixInvalid as n, ObjectExpiry as r, ExpiryDaysInvalid as t };
+//# sourceMappingURL=expire-C586zznE.d.mts.map

package/dist/expire-C586zznE.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expire-C586zznE.d.mts","names":[],"sources":["../src/expire.ts"],"mappings":";;;;;;;;;;;;;;;;;;KAiBY,eAAe,SAAS;WAA0B;;;cAGjD,4BAA4B;WAE9B;WACA;WACA;EAHV,YACU,gBACA,gBACA;;;cAWE,0BAA0B;WAE5B;WACA;WACA;EAHV,YACU,gBACA,gBACA"}

package/dist/expire-CieftS01.cjs

@@ -0,0 +1,67 @@
+//#region src/expire.ts
+/** An expiry prefix the bucket could not match the way it reads. */
+var ExpiryPrefixInvalid = class extends Error {
+	bucket;
+	prefix;
+	reason;
+	constructor(bucket, prefix, reason) {
+		super(`'${bucket}' expires objects under '${prefix}', which ${reason}. Name the start of the keys as they are stored, e.g. 'quotes/'.`);
+		this.bucket = bucket;
+		this.prefix = prefix;
+		this.reason = reason;
+		this.name = "ExpiryPrefixInvalid";
+	}
+};
+/** An expiry that is not a whole number of days, one or more. */
+var ExpiryDaysInvalid = class extends Error {
+	bucket;
+	prefix;
+	days;
+	constructor(bucket, prefix, days) {
+		super(`'${bucket}' expires '${prefix}' after ${String(days)} days. A bucket counts lifecycle in whole days, so give an integer of 1 or more.`);
+		this.bucket = bucket;
+		this.prefix = prefix;
+		this.days = days;
+		this.name = "ExpiryDaysInvalid";
+	}
+};
+/**
+* The expiry as the manifest records it — prefix → days — after checking
+* each entry, or nothing when there is none.
+*
+* @throws {ExpiryPrefixInvalid} for an empty, rooted or globbed prefix
+* @throws {ExpiryDaysInvalid} for anything but a positive integer of days
+*/
+function expiryDays(bucket, expire) {
+	if (!expire) return void 0;
+	const days = {};
+	for (const [prefix, { days: count }] of Object.entries(expire)) {
+		if (prefix.length === 0) throw new ExpiryPrefixInvalid(bucket, prefix, "is empty");
+		if (prefix.startsWith("/")) throw new ExpiryPrefixInvalid(bucket, prefix, "starts with '/', which no stored key does");
+		if (/[*?]/.test(prefix)) throw new ExpiryPrefixInvalid(bucket, prefix, "is a pattern, and a lifecycle prefix is matched literally");
+		if (!Number.isInteger(count) || count < 1) throw new ExpiryDaysInvalid(bucket, prefix, count);
+		days[prefix] = count;
+	}
+	return Object.keys(days).length > 0 ? days : void 0;
+}
+//#endregion
+Object.defineProperty(exports, "ExpiryDaysInvalid", {
+	enumerable: true,
+	get: function() {
+		return ExpiryDaysInvalid;
+	}
+});
+Object.defineProperty(exports, "ExpiryPrefixInvalid", {
+	enumerable: true,
+	get: function() {
+		return ExpiryPrefixInvalid;
+	}
+});
+Object.defineProperty(exports, "expiryDays", {
+	enumerable: true,
+	get: function() {
+		return expiryDays;
+	}
+});
+
+//# sourceMappingURL=expire-CieftS01.cjs.map

package/dist/expire-CieftS01.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"expire-CieftS01.cjs","names":[],"sources":["../src/expire.ts"],"sourcesContent":["/**\n * How long a bucket keeps the objects under a prefix.\n *\n * Shared by `ObjectStorage` and the bucket a `FileServer` vends, because it is\n * a fact about the bucket rather than about who serves it: a prefix of\n * generated files that nobody reads back grows for ever unless the bucket\n * itself is told to drop them.\n *\n * ```ts\n * new ObjectStorage('Private', { expire: { 'quotes/': { days: 30 } } });\n * ```\n *\n * Whole days, because that is the unit S3's lifecycle — and MinIO's — counts\n * in. Prefixes are literal: a lifecycle rule matches the start of a key and\n * has no globs, so a pattern that looks like one is refused rather than\n * silently matching nothing.\n */\nexport type ObjectExpiry = Readonly<Record<string, { readonly days: number }>>;\n\n/** An expiry prefix the bucket could not match the way it reads. */\nexport class ExpiryPrefixInvalid extends Error {\n\tconstructor(\n\t\treadonly bucket: string,\n\t\treadonly prefix: string,\n\t\treadonly reason: string,\n\t) {\n\t\tsuper(\n\t\t\t`'${bucket}' expires objects under '${prefix}', which ${reason}. ` +\n\t\t\t\t`Name the start of the keys as they are stored, e.g. 'quotes/'.`,\n\t\t);\n\t\tthis.name = 'ExpiryPrefixInvalid';\n\t}\n}\n\n/** An expiry that is not a whole number of days, one or more. */\nexport class ExpiryDaysInvalid extends Error {\n\tconstructor(\n\t\treadonly bucket: string,\n\t\treadonly prefix: string,\n\t\treadonly days: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`'${bucket}' expires '${prefix}' after ${String(days)} days. A bucket ` +\n\t\t\t\t`counts lifecycle in whole days, so give an integer of 1 or more.`,\n\t\t);\n\t\tthis.name = 'ExpiryDaysInvalid';\n\t}\n}\n\n/**\n * The expiry as the manifest records it — prefix → days — after checking\n * each entry, or nothing when there is none.\n *\n * @throws {ExpiryPrefixInvalid} for an empty, rooted or globbed prefix\n * @throws {ExpiryDaysInvalid} for anything but a positive integer of days\n */\nexport function expiryDays(\n\tbucket: string,\n\texpire: ObjectExpiry | undefined,\n): Record<string, number> | undefined {\n\tif (!expire) return undefined;\n\n\tconst days: Record<string, number> = {};\n\tfor (const [prefix, { days: count }] of Object.entries(expire)) {\n\t\tif (prefix.length === 0) {\n\t\t\tthrow new ExpiryPrefixInvalid(bucket, prefix, 'is empty');\n\t\t}\n\t\tif (prefix.startsWith('/')) {\n\t\t\tthrow new ExpiryPrefixInvalid(\n\t\t\t\tbucket,\n\t\t\t\tprefix,\n\t\t\t\t\"starts with '/', which no stored key does\",\n\t\t\t);\n\t\t}\n\t\tif (/[*?]/.test(prefix)) {\n\t\t\tthrow new ExpiryPrefixInvalid(\n\t\t\t\tbucket,\n\t\t\t\tprefix,\n\t\t\t\t'is a pattern, and a lifecycle prefix is matched literally',\n\t\t\t);\n\t\t}\n\t\tif (!Number.isInteger(count) || count < 1) {\n\t\t\tthrow new ExpiryDaysInvalid(bucket, prefix, count);\n\t\t}\n\t\tdays[prefix] = count;\n\t}\n\n\treturn Object.keys(days).length > 0 ? days : undefined;\n}\n"],"mappings":";;AAoBA,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CACA;CAHV,YACC,QACA,QACA,QACC;EACD,MACC,IAAI,OAAO,2BAA2B,OAAO,WAAW,OAAO,iEAEhE;EAPS,KAAA,SAAA;EACA,KAAA,SAAA;EACA,KAAA,SAAA;EAMT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,oBAAb,cAAuC,MAAM;CAElC;CACA;CACA;CAHV,YACC,QACA,QACA,MACC;EACD,MACC,IAAI,OAAO,aAAa,OAAO,UAAU,OAAO,IAAI,EAAE,iFAEvD;EAPS,KAAA,SAAA;EACA,KAAA,SAAA;EACA,KAAA,OAAA;EAMT,KAAK,OAAO;CACb;AACD;;;;;;;;AASA,SAAgB,WACf,QACA,QACqC;CACrC,IAAI,CAAC,QAAQ,OAAO,KAAA;CAEpB,MAAM,OAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,QAAQ,EAAE,MAAM,YAAY,OAAO,QAAQ,MAAM,GAAG;EAC/D,IAAI,OAAO,WAAW,GACrB,MAAM,IAAI,oBAAoB,QAAQ,QAAQ,UAAU;EAEzD,IAAI,OAAO,WAAW,GAAG,GACxB,MAAM,IAAI,oBACT,QACA,QACA,2CACD;EAED,IAAI,OAAO,KAAK,MAAM,GACrB,MAAM,IAAI,oBACT,QACA,QACA,2DACD;EAED,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,GACvC,MAAM,IAAI,kBAAkB,QAAQ,QAAQ,KAAK;EAElD,KAAK,UAAU;CAChB;CAEA,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,IAAI,OAAO,KAAA;AAC9C"}

package/dist/expire-CpzUAfr9.mjs

@@ -0,0 +1,50 @@
+//#region src/expire.ts
+/** An expiry prefix the bucket could not match the way it reads. */
+var ExpiryPrefixInvalid = class extends Error {
+	bucket;
+	prefix;
+	reason;
+	constructor(bucket, prefix, reason) {
+		super(`'${bucket}' expires objects under '${prefix}', which ${reason}. Name the start of the keys as they are stored, e.g. 'quotes/'.`);
+		this.bucket = bucket;
+		this.prefix = prefix;
+		this.reason = reason;
+		this.name = "ExpiryPrefixInvalid";
+	}
+};
+/** An expiry that is not a whole number of days, one or more. */
+var ExpiryDaysInvalid = class extends Error {
+	bucket;
+	prefix;
+	days;
+	constructor(bucket, prefix, days) {
+		super(`'${bucket}' expires '${prefix}' after ${String(days)} days. A bucket counts lifecycle in whole days, so give an integer of 1 or more.`);
+		this.bucket = bucket;
+		this.prefix = prefix;
+		this.days = days;
+		this.name = "ExpiryDaysInvalid";
+	}
+};
+/**
+* The expiry as the manifest records it — prefix → days — after checking
+* each entry, or nothing when there is none.
+*
+* @throws {ExpiryPrefixInvalid} for an empty, rooted or globbed prefix
+* @throws {ExpiryDaysInvalid} for anything but a positive integer of days
+*/
+function expiryDays(bucket, expire) {
+	if (!expire) return void 0;
+	const days = {};
+	for (const [prefix, { days: count }] of Object.entries(expire)) {
+		if (prefix.length === 0) throw new ExpiryPrefixInvalid(bucket, prefix, "is empty");
+		if (prefix.startsWith("/")) throw new ExpiryPrefixInvalid(bucket, prefix, "starts with '/', which no stored key does");
+		if (/[*?]/.test(prefix)) throw new ExpiryPrefixInvalid(bucket, prefix, "is a pattern, and a lifecycle prefix is matched literally");
+		if (!Number.isInteger(count) || count < 1) throw new ExpiryDaysInvalid(bucket, prefix, count);
+		days[prefix] = count;
+	}
+	return Object.keys(days).length > 0 ? days : void 0;
+}
+//#endregion
+export { ExpiryPrefixInvalid as n, expiryDays as r, ExpiryDaysInvalid as t };
+
+//# sourceMappingURL=expire-CpzUAfr9.mjs.map

package/dist/expire-CpzUAfr9.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"expire-CpzUAfr9.mjs","names":[],"sources":["../src/expire.ts"],"sourcesContent":["/**\n * How long a bucket keeps the objects under a prefix.\n *\n * Shared by `ObjectStorage` and the bucket a `FileServer` vends, because it is\n * a fact about the bucket rather than about who serves it: a prefix of\n * generated files that nobody reads back grows for ever unless the bucket\n * itself is told to drop them.\n *\n * ```ts\n * new ObjectStorage('Private', { expire: { 'quotes/': { days: 30 } } });\n * ```\n *\n * Whole days, because that is the unit S3's lifecycle — and MinIO's — counts\n * in. Prefixes are literal: a lifecycle rule matches the start of a key and\n * has no globs, so a pattern that looks like one is refused rather than\n * silently matching nothing.\n */\nexport type ObjectExpiry = Readonly<Record<string, { readonly days: number }>>;\n\n/** An expiry prefix the bucket could not match the way it reads. */\nexport class ExpiryPrefixInvalid extends Error {\n\tconstructor(\n\t\treadonly bucket: string,\n\t\treadonly prefix: string,\n\t\treadonly reason: string,\n\t) {\n\t\tsuper(\n\t\t\t`'${bucket}' expires objects under '${prefix}', which ${reason}. ` +\n\t\t\t\t`Name the start of the keys as they are stored, e.g. 'quotes/'.`,\n\t\t);\n\t\tthis.name = 'ExpiryPrefixInvalid';\n\t}\n}\n\n/** An expiry that is not a whole number of days, one or more. */\nexport class ExpiryDaysInvalid extends Error {\n\tconstructor(\n\t\treadonly bucket: string,\n\t\treadonly prefix: string,\n\t\treadonly days: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`'${bucket}' expires '${prefix}' after ${String(days)} days. A bucket ` +\n\t\t\t\t`counts lifecycle in whole days, so give an integer of 1 or more.`,\n\t\t);\n\t\tthis.name = 'ExpiryDaysInvalid';\n\t}\n}\n\n/**\n * The expiry as the manifest records it — prefix → days — after checking\n * each entry, or nothing when there is none.\n *\n * @throws {ExpiryPrefixInvalid} for an empty, rooted or globbed prefix\n * @throws {ExpiryDaysInvalid} for anything but a positive integer of days\n */\nexport function expiryDays(\n\tbucket: string,\n\texpire: ObjectExpiry | undefined,\n): Record<string, number> | undefined {\n\tif (!expire) return undefined;\n\n\tconst days: Record<string, number> = {};\n\tfor (const [prefix, { days: count }] of Object.entries(expire)) {\n\t\tif (prefix.length === 0) {\n\t\t\tthrow new ExpiryPrefixInvalid(bucket, prefix, 'is empty');\n\t\t}\n\t\tif (prefix.startsWith('/')) {\n\t\t\tthrow new ExpiryPrefixInvalid(\n\t\t\t\tbucket,\n\t\t\t\tprefix,\n\t\t\t\t\"starts with '/', which no stored key does\",\n\t\t\t);\n\t\t}\n\t\tif (/[*?]/.test(prefix)) {\n\t\t\tthrow new ExpiryPrefixInvalid(\n\t\t\t\tbucket,\n\t\t\t\tprefix,\n\t\t\t\t'is a pattern, and a lifecycle prefix is matched literally',\n\t\t\t);\n\t\t}\n\t\tif (!Number.isInteger(count) || count < 1) {\n\t\t\tthrow new ExpiryDaysInvalid(bucket, prefix, count);\n\t\t}\n\t\tdays[prefix] = count;\n\t}\n\n\treturn Object.keys(days).length > 0 ? days : undefined;\n}\n"],"mappings":";;AAoBA,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CACA;CAHV,YACC,QACA,QACA,QACC;EACD,MACC,IAAI,OAAO,2BAA2B,OAAO,WAAW,OAAO,iEAEhE;EAPS,KAAA,SAAA;EACA,KAAA,SAAA;EACA,KAAA,SAAA;EAMT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,oBAAb,cAAuC,MAAM;CAElC;CACA;CACA;CAHV,YACC,QACA,QACA,MACC;EACD,MACC,IAAI,OAAO,aAAa,OAAO,UAAU,OAAO,IAAI,EAAE,iFAEvD;EAPS,KAAA,SAAA;EACA,KAAA,SAAA;EACA,KAAA,OAAA;EAMT,KAAK,OAAO;CACb;AACD;;;;;;;;AASA,SAAgB,WACf,QACA,QACqC;CACrC,IAAI,CAAC,QAAQ,OAAO,KAAA;CAEpB,MAAM,OAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,QAAQ,EAAE,MAAM,YAAY,OAAO,QAAQ,MAAM,GAAG;EAC/D,IAAI,OAAO,WAAW,GACrB,MAAM,IAAI,oBAAoB,QAAQ,QAAQ,UAAU;EAEzD,IAAI,OAAO,WAAW,GAAG,GACxB,MAAM,IAAI,oBACT,QACA,QACA,2CACD;EAED,IAAI,OAAO,KAAK,MAAM,GACrB,MAAM,IAAI,oBACT,QACA,QACA,2DACD;EAED,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,GACvC,MAAM,IAAI,kBAAkB,QAAQ,QAAQ,KAAK;EAElD,KAAK,UAAU;CAChB;CAEA,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,IAAI,OAAO,KAAA;AAC9C"}

package/dist/external-api.cjs

@@ -0,0 +1,106 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_credential = require("./credential-DYymbp_7.cjs");
+const require_tracing = require("./tracing-C0ooU0V2.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+//#region src/external-api.ts
+/**
+* `ExternalApi` — an HTTP API somebody else runs.
+*
+* Polar, Stripe, a payment gateway: nothing to provision, but an address that
+* changes by stage and credentials the provider issued for each one. Without a
+* construct every integration writes that switching by hand — an optional
+* `POLAR_URL`, a fake started somewhere, a client built in a service — and the
+* target cannot see any of it.
+*
+* ```ts
+* // constructs/polar.ts
+* export const polar = new ExternalApi('Polar', {
+*   url: 'https://www.polaraccesslink.com',
+*   credentials: z.object({ clientId: z.string(), clientSecret: z.string() }),
+*   client: ({ url, credentials }) => new PolarClient(url, credentials),
+* });
+*
+* // test/fakes/polar.ts
+* export default fake.app(new Hono().post('/v3/oauth2/token', …), {
+*   credentials: { clientId: 'fake', clientSecret: 'fake' },
+* });
+*
+* // in a handler — the real API deployed, the fake locally and in tests
+* .dependsOn([polar])
+* .handle(({ services }) => services.polar.exchangeCode(code))
+* ```
+*
+* Deployed, the URL is `url` — one for every stage, or one per stage name with
+* a `default` — and the credentials are the stage's `<ID>_CREDENTIALS`, one
+* JSON value read the way a `Credential`'s is. Locally and in tests both come
+* from the fake.
+*
+* **The construct never names its fake.** It is found by convention, at
+* `test/fakes/<id>.ts`, and read only by gkm and the generated test harness —
+* so a fake, and the recorded responses it answers from, cannot end up in a
+* deployed bundle however the bundler follows imports.
+*/
+var ExternalApi = class {
+	options;
+	id;
+	service;
+	/** Read by both `declare()` and `connect()`, so the two cannot drift. */
+	keys;
+	/** The promise, so concurrent registrations share one client. */
+	connected;
+	constructor(id, options) {
+		this.options = options;
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
+		this.id = canonical;
+		this.keys = {
+			url: (0, _geekmidas_manifest.provideKey)(canonical, "url"),
+			credentials: (0, _geekmidas_manifest.provideKey)(canonical, "credentials")
+		};
+		this.service = {
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
+			register: (registerOptions) => {
+				this.connected ??= this.connect(registerOptions);
+				return this.connected;
+			}
+		};
+	}
+	/**
+	* What the stage's `<ID>_CREDENTIALS` must look like — the schema the value
+	* is validated against where it is read. Public so a tool setting the value
+	* (`gkm secrets:add`) can check it, and describe its fields, before it is
+	* stored rather than at the first request.
+	*/
+	get credentialsSchema() {
+		return this.options.credentials;
+	}
+	declare() {
+		return [{
+			kind: "external-api",
+			id: this.id,
+			url: this.options.url,
+			provides: [this.keys.url, this.keys.credentials]
+		}];
+	}
+	async connect(options) {
+		const { url } = options.envParser.create((get) => ({ url: get(this.keys.url).string() })).parse();
+		const credentials = await require_credential.readCredentials(this.id, this.keys.credentials, this.options.credentials, options.envParser);
+		const client = await this.options.client({
+			url,
+			credentials
+		});
+		return require_tracing.traceClient(this.id, client, { "server.address": hostOf(url) });
+	}
+};
+function hostOf(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return url;
+	}
+}
+//#endregion
+exports.ExternalApi = ExternalApi;
+exports.fake = require_credential.fake;
+exports.isFake = require_credential.isFake;
+
+//# sourceMappingURL=external-api.cjs.map

package/dist/external-api.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api.cjs","names":["canonicalId","provideKey","serviceKey","readCredentials","traceClient"],"sources":["../src/external-api.ts"],"sourcesContent":["/**\n * `ExternalApi` — an HTTP API somebody else runs.\n *\n * Polar, Stripe, a payment gateway: nothing to provision, but an address that\n * changes by stage and credentials the provider issued for each one. Without a\n * construct every integration writes that switching by hand — an optional\n * `POLAR_URL`, a fake started somewhere, a client built in a service — and the\n * target cannot see any of it.\n *\n * ```ts\n * // constructs/polar.ts\n * export const polar = new ExternalApi('Polar', {\n *   url: 'https://www.polaraccesslink.com',\n *   credentials: z.object({ clientId: z.string(), clientSecret: z.string() }),\n *   client: ({ url, credentials }) => new PolarClient(url, credentials),\n * });\n *\n * // test/fakes/polar.ts\n * export default fake.app(new Hono().post('/v3/oauth2/token', …), {\n *   credentials: { clientId: 'fake', clientSecret: 'fake' },\n * });\n *\n * // in a handler — the real API deployed, the fake locally and in tests\n * .dependsOn([polar])\n * .handle(({ services }) => services.polar.exchangeCode(code))\n * ```\n *\n * Deployed, the URL is `url` — one for every stage, or one per stage name with\n * a `default` — and the credentials are the stage's `<ID>_CREDENTIALS`, one\n * JSON value read the way a `Credential`'s is. Locally and in tests both come\n * from the fake.\n *\n * **The construct never names its fake.** It is found by convention, at\n * `test/fakes/<id>.ts`, and read only by gkm and the generated test harness —\n * so a fake, and the recorded responses it answers from, cannot end up in a\n * deployed bundle however the bundler follows imports.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\nimport { readCredentials } from './credential';\nimport type { DeployedStage, LocalStage } from './stages';\nimport { traceClient } from './tracing';\n\n/** What a credentials schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\n/**\n * Where an external API answers: one URL for every stage, or one per stage\n * name with `default` for any stage not listed.\n *\n * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,\n * so a key that names no stage — `prodution` — is a type error rather than a\n * URL nothing reads. Without the file any key goes, as before.\n */\nexport type ExternalApiUrl =\n\t| string\n\t| (string extends LocalStage | DeployedStage\n\t\t\t? Readonly<Record<string, string>>\n\t\t\t: { readonly [S in LocalStage | DeployedStage]?: string } & {\n\t\t\t\t\treadonly default?: string;\n\t\t\t\t});\n\nexport interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {\n\t/**\n\t * Where it answers deployed: one URL for every stage, or one per stage\n\t * name, with `default` for any stage not listed.\n\t */\n\turl: ExternalApiUrl;\n\t/** What the stage's `<ID>_CREDENTIALS` must look like. */\n\tcredentials: TSchema;\n\t/** What a handler is handed, built from where it answers and the credentials. */\n\tclient: (connection: {\n\t\turl: string;\n\t\tcredentials: Value<TSchema>;\n\t}) => TClient | Promise<TClient>;\n}\n\nexport class ExternalApi<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n\tTClient = unknown,\n> implements Consumable<TName, TClient>\n{\n\t// `Consumable` for the reason `Credential` gives: a client generic in\n\t// `TClient` cannot satisfy `Construct`'s conditional service type.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, TClient>;\n\n\t/** Read by both `declare()` and `connect()`, so the two cannot drift. */\n\tprivate readonly keys: { url: string; credentials: string };\n\n\t/** The promise, so concurrent registrations share one client. */\n\tprivate connected?: Promise<TClient>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: ExternalApiOptions<TSchema, TClient>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\tcredentials: provideKey(canonical, 'credentials'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => {\n\t\t\t\tthis.connected ??= this.connect(registerOptions);\n\t\t\t\treturn this.connected;\n\t\t\t},\n\t\t};\n\t}\n\n\t/**\n\t * What the stage's `<ID>_CREDENTIALS` must look like — the schema the value\n\t * is validated against where it is read. Public so a tool setting the value\n\t * (`gkm secrets:add`) can check it, and describe its fields, before it is\n\t * stored rather than at the first request.\n\t */\n\tget credentialsSchema(): TSchema {\n\t\treturn this.options.credentials;\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'external-api',\n\t\t\t\tid: this.id,\n\t\t\t\t// The stage-keyed map is a record of URLs to the manifest, which\n\t\t\t\t// reads it by whatever stage it is resolving.\n\t\t\t\turl: this.options.url as Readonly<Record<string, string>> | string,\n\t\t\t\tprovides: [this.keys.url, this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate async connect(options: ServiceRegisterOptions): Promise<TClient> {\n\t\tconst { url } = options.envParser\n\t\t\t.create((get) => ({ url: get(this.keys.url).string() }))\n\t\t\t.parse();\n\t\tconst credentials = await readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.credentials,\n\t\t\toptions.envParser,\n\t\t);\n\n\t\tconst client = await this.options.client({ url, credentials });\n\t\t// Each call a span carrying this API's name — the parent of the fetch\n\t\t// it makes, which is traced already.\n\t\treturn traceClient(this.id, client, {\n\t\t\t'server.address': hostOf(url),\n\t\t});\n\t}\n}\n\nfunction hostOf(url: string): string {\n\ttry {\n\t\treturn new URL(url).host;\n\t} catch {\n\t\treturn url;\n\t}\n}\n\nexport {\n\ttype Fake,\n\ttype FetchHandler,\n\tfake,\n\tisFake,\n} from './fake';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuFA,IAAa,cAAb,MAKA;CAcmB;CAXlB;CACA;;CAGA;;CAGA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,aAAA,GAAYA,oBAAAA,YAAAA,CAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO;GACX,MAAA,GAAKC,oBAAAA,WAAAA,CAAW,WAAW,KAAK;GAChC,cAAA,GAAaA,oBAAAA,WAAAA,CAAW,WAAW,aAAa;EACjD;EAGA,KAAK,UAAU;GACd,cAAA,GAAaC,oBAAAA,WAAAA,CAAW,SAAS;GACjC,WAAW,oBAAoB;IAC9B,KAAK,cAAc,KAAK,QAAQ,eAAe;IAC/C,OAAO,KAAK;GACb;EACD;CACD;;;;;;;CAQA,IAAI,oBAA6B;EAChC,OAAO,KAAK,QAAQ;CACrB;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GAGT,KAAK,KAAK,QAAQ;GAClB,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,WAAW;EAChD,CACD;CACD;CAEA,MAAc,QAAQ,SAAmD;EACxE,MAAM,EAAE,QAAQ,QAAQ,UACtB,QAAQ,SAAS,EAAE,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CACvD,MAAM;EACR,MAAM,cAAc,MAAMC,mBAAAA,gBACzB,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,aACb,QAAQ,SACT;EAEA,MAAM,SAAS,MAAM,KAAK,QAAQ,OAAO;GAAE;GAAK;EAAY,CAAC;EAG7D,OAAOC,gBAAAA,YAAY,KAAK,IAAI,QAAQ,EACnC,kBAAkB,OAAO,GAAG,EAC7B,CAAC;CACF;AACD;AAEA,SAAS,OAAO,KAAqB;CACpC,IAAI;EACH,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACrB,QAAQ;EACP,OAAO;CACR;AACD"}

package/dist/external-api.d.cts

@@ -0,0 +1,2 @@
+import { a as ExternalApi, i as isFake, n as FetchHandler, o as ExternalApiOptions, r as fake, s as ExternalApiUrl, t as Fake } from "./fake-B7rvi4Qp.cjs";
+export { ExternalApi, ExternalApiOptions, ExternalApiUrl, type Fake, type FetchHandler, fake, isFake };

package/dist/external-api.d.mts

@@ -0,0 +1,2 @@
+import { a as ExternalApi, i as isFake, n as FetchHandler, o as ExternalApiOptions, r as fake, s as ExternalApiUrl, t as Fake } from "./fake-JXbkdao8.mjs";
+export { ExternalApi, ExternalApiOptions, ExternalApiUrl, type Fake, type FetchHandler, fake, isFake };