@geekmidas/constructs 10.0.0-alpha.37 → 10.0.0-alpha.39

package/dist/crons/index.d.cts

@@ -1,5 +1,5 @@
-import { i as ScheduleExpression, n as CronExpression, r as RateExpression, t as Cron } from "../Cron-CA2oa2nC.cjs";
-import { t as CronBuilder } from "../CronBuilder-B_KqaodP.cjs";
+import { i as ScheduleExpression, n as CronExpression, r as RateExpression, t as Cron } from "../Cron-CMEGfRs8.cjs";
+import { t as CronBuilder } from "../CronBuilder-CEK7aOqD.cjs";
 //#region src/crons/schedule.d.ts
 /**
  * A schedule a cron runner can take, as standard five-field cron.

package/dist/crons/index.d.mts

@@ -1,5 +1,5 @@
-import { i as ScheduleExpression, n as CronExpression, r as RateExpression, t as Cron } from "../Cron-B_iuyNxr.mjs";
-import { t as CronBuilder } from "../CronBuilder-BIKCLWu7.mjs";
+import { i as ScheduleExpression, n as CronExpression, r as RateExpression, t as Cron } from "../Cron-D6X4-xjB.mjs";
+import { t as CronBuilder } from "../CronBuilder-O_gvButp.mjs";
 //#region src/crons/schedule.d.ts
 /**
  * A schedule a cron runner can take, as standard five-field cron.

package/dist/crons/index.mjs

@@ -1,4 +1,4 @@
-import { n as Cron, t as CronBuilder } from "../CronBuilder-BRkzUOAs.mjs";
+import { n as Cron, t as CronBuilder } from "../CronBuilder-Dv0IlZs0.mjs";
 //#region src/crons/schedule.ts
 /**
 * A schedule a cron runner can take, as standard five-field cron.

package/dist/database/kysely.d.cts

@@ -1,2 +1,2 @@
-import { n as KyselyDatabaseOptions, r as ReadOnlyDatabase, t as KyselyDatabase } from "../kysely-CEVXacPN.cjs";
+import { n as KyselyDatabaseOptions, r as ReadOnlyDatabase, t as KyselyDatabase } from "../kysely-DVF8wOT4.cjs";
 export { KyselyDatabase, KyselyDatabaseOptions, ReadOnlyDatabase };

package/dist/database/kysely.d.mts

@@ -1,2 +1,2 @@
-import { n as KyselyDatabaseOptions, r as ReadOnlyDatabase, t as KyselyDatabase } from "../kysely-mcTdPNhl.mjs";
+import { n as KyselyDatabaseOptions, r as ReadOnlyDatabase, t as KyselyDatabase } from "../kysely-BJ8IQ_1P.mjs";
 export { KyselyDatabase, KyselyDatabaseOptions, ReadOnlyDatabase };

package/dist/email.d.cts

@@ -1,4 +1,4 @@
-import { n as Construct } from "./construct-interface-DPusCUSQ.cjs";
+import { n as Construct } from "./construct-interface-_xi4BPN8.cjs";
 import { Service } from "@geekmidas/services";
 import { ConstructName, Declaration } from "@geekmidas/manifest";
 import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";

package/dist/email.d.mts

@@ -1,4 +1,4 @@
-import { n as Construct } from "./construct-interface-D2gesxos.mjs";
+import { n as Construct } from "./construct-interface-_3zgxzXl.mjs";
 import { ConstructName, Declaration } from "@geekmidas/manifest";
 import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";
 import { Service } from "@geekmidas/services";

package/dist/endpoints/index.cjs

@@ -1,8 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_EndpointFactory = require("../EndpointFactory-BmO0WnXE.cjs");
-const require_Endpoint = require("../Endpoint-QKuFg5gs.cjs");
+const require_EndpointFactory = require("../EndpointFactory-BZOCOaK6.cjs");
+const require_functions = require("../functions-ZH60FE7H.cjs");
+const require_Endpoint = require("../Endpoint-D1L9qu5C.cjs");
 const require_surfaceEnv = require("../surfaceEnv-CNimK76p.cjs");
-const require_lazyAccessors = require("../lazyAccessors-Dx9NLwJZ.cjs");
+const require_lazyAccessors = require("../lazyAccessors-hJKGv8Ay.cjs");
 exports.BUILT_IN_SECURITY_SCHEMES = require_EndpointFactory.BUILT_IN_SECURITY_SCHEMES;
 exports.Endpoint = require_Endpoint.Endpoint;
 exports.EndpointBuilder = require_EndpointFactory.EndpointBuilder;
@@ -21,4 +22,4 @@ exports.defaultEnvParser = require_surfaceEnv.defaultEnvParser;
 exports.envParserFor = require_surfaceEnv.envParserFor;
 exports.getSecurityScheme = require_EndpointFactory.getSecurityScheme;
 exports.isBuiltInSecurityScheme = require_EndpointFactory.isBuiltInSecurityScheme;
-exports.publishConstructEvents = require_lazyAccessors.publishConstructEvents;
+exports.publishConstructEvents = require_functions.publishConstructEvents;

package/dist/endpoints/index.d.cts

@@ -1,17 +1,8 @@
-import { t as StandardSchemaV1 } from "../index-CeEtxDmK.cjs";
-import { t as Construct } from "../Construct-DTqYvkPG.cjs";
-import { A as getSecurityScheme, C as Authorizer, D as OAuthFlows, E as OAuthFlow, O as SecurityScheme, S as MappedAudit, T as BuiltInSecuritySchemeId, _ as RlsBypass, a as EndpointContext, b as RlsContextExtractor, c as EndpointSchemas, d as ResponseBuilder, g as RLS_BYPASS, h as SessionAuth, i as Endpoint, j as isBuiltInSecurityScheme, k as createAuthorizer, l as EndpointSurface, m as NoAuthenticator, n as ConvertRouteParams, o as EndpointHandler, r as CookieFn, s as EndpointOutput, u as HeaderFn, v as RlsConfig, w as BUILT_IN_SECURITY_SCHEMES, x as ActorExtractor, y as RlsContext } from "../Endpoint-1-XYQSx0.cjs";
-import { n as EndpointBuilder, t as EndpointFactory } from "../EndpointFactory-BnK_YkW1.cjs";
+import { s as publishConstructEvents } from "../Construct-BQALFCh2.cjs";
+import { A as getSecurityScheme, C as Authorizer, D as OAuthFlows, E as OAuthFlow, O as SecurityScheme, S as MappedAudit, T as BuiltInSecuritySchemeId, _ as RlsBypass, a as EndpointContext, b as RlsContextExtractor, c as EndpointSchemas, d as ResponseBuilder, g as RLS_BYPASS, h as SessionAuth, i as Endpoint, j as isBuiltInSecurityScheme, k as createAuthorizer, l as EndpointSurface, m as NoAuthenticator, n as ConvertRouteParams, o as EndpointHandler, r as CookieFn, s as EndpointOutput, u as HeaderFn, v as RlsConfig, w as BUILT_IN_SECURITY_SCHEMES, x as ActorExtractor, y as RlsContext } from "../Endpoint-Dp5AKIXl.cjs";
+import { n as EndpointBuilder, t as EndpointFactory } from "../EndpointFactory-FeFRmlDZ.cjs";
 import { EnvironmentParser } from "@geekmidas/envkit";
-import { EventPublisher, MappedEvent } from "@geekmidas/events";
-import { Logger } from "@geekmidas/logger";
-import { InferStandardSchema } from "@geekmidas/schema";
-import { Service, ServiceDiscovery } from "@geekmidas/services";
-import { AuditStorage } from "@geekmidas/audit";
 import { Context } from "hono";
-//#region src/publisher.d.ts
-export declare function publishConstructEvents<T extends EventPublisher<any> | undefined, OutSchema extends StandardSchemaV1 | undefined = undefined, TServiceName extends string = string, TServices extends Service[] = [], TAuditStorageServiceName extends string = string, TAuditStorage extends AuditStorage | undefined = undefined>(construct: Construct<Logger, TServiceName, T, OutSchema, TServices, TAuditStorageServiceName, TAuditStorage>, response: InferStandardSchema<OutSchema>, serviceDiscovery: ServiceDiscovery<any>, logger?: Logger): Promise<void>;
-//#endregion
 //#region src/endpoints/lazyAccessors.d.ts
 /**
  * Create a lazy header accessor for Hono.
@@ -56,5 +47,5 @@ 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 MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme };
+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 MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
 //# sourceMappingURL=index.d.cts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/publisher.ts","../../src/endpoints/lazyAccessors.ts","../../src/endpoints/surfaceEnv.ts"],"mappings":";;;;;;;;;;;;wBAgEsB,uBACrB,UAAU,iCACV,kBAAkB,0CAClB,sCACA,kBAAkB,gBAClB,kDACA,sBAAsB,sCAEtB,WAAW,UACV,QACA,cACA,GACA,WACA,WACA,0BACA,gBAED,UAAU,oBAAoB,YAC9B,kBAAkB,uBAClB,SAAQ,SAAyB;;;;;;;;wBCnElB,kBAAkB,GAAG,UAAU;;;;;;wBAqB/B,kBAAkB,GAAG,UAAU;;;;;wBAgC/B,wBACf,SAAS,wDACP;;;;;wBAoCa,wBACf,+BACA,mCACE;;;;wBAmHa,qBAAqB;;;;wBAUrB,qBAAqB;;;;;;;;;;wBC1MrB,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/endpoints/lazyAccessors.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;;;;;;;;;;wBC1MrB,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}

package/dist/endpoints/index.d.mts

@@ -1,17 +1,8 @@
-import { t as StandardSchemaV1 } from "../index-CeEtxDmK.mjs";
-import { t as Construct } from "../Construct-pVadmURD.mjs";
-import { A as getSecurityScheme, C as Authorizer, D as OAuthFlows, E as OAuthFlow, O as SecurityScheme, S as MappedAudit, T as BuiltInSecuritySchemeId, _ as RlsBypass, a as EndpointContext, b as RlsContextExtractor, c as EndpointSchemas, d as ResponseBuilder, g as RLS_BYPASS, h as SessionAuth, i as Endpoint, j as isBuiltInSecurityScheme, k as createAuthorizer, l as EndpointSurface, m as NoAuthenticator, n as ConvertRouteParams, o as EndpointHandler, r as CookieFn, s as EndpointOutput, u as HeaderFn, v as RlsConfig, w as BUILT_IN_SECURITY_SCHEMES, x as ActorExtractor, y as RlsContext } from "../Endpoint-GFIxYb9L.mjs";
-import { n as EndpointBuilder, t as EndpointFactory } from "../EndpointFactory-BCZdh_u3.mjs";
+import { s as publishConstructEvents } from "../Construct-QXnl3VqT.mjs";
+import { A as getSecurityScheme, C as Authorizer, D as OAuthFlows, E as OAuthFlow, O as SecurityScheme, S as MappedAudit, T as BuiltInSecuritySchemeId, _ as RlsBypass, a as EndpointContext, b as RlsContextExtractor, c as EndpointSchemas, d as ResponseBuilder, g as RLS_BYPASS, h as SessionAuth, i as Endpoint, j as isBuiltInSecurityScheme, k as createAuthorizer, l as EndpointSurface, m as NoAuthenticator, n as ConvertRouteParams, o as EndpointHandler, r as CookieFn, s as EndpointOutput, u as HeaderFn, v as RlsConfig, w as BUILT_IN_SECURITY_SCHEMES, x as ActorExtractor, y as RlsContext } from "../Endpoint-DtI7heFm.mjs";
+import { n as EndpointBuilder, t as EndpointFactory } from "../EndpointFactory-CgMDvERK.mjs";
 import { EnvironmentParser } from "@geekmidas/envkit";
-import { EventPublisher, MappedEvent } from "@geekmidas/events";
-import { Service, ServiceDiscovery } from "@geekmidas/services";
 import { Context } from "hono";
-import { AuditStorage } from "@geekmidas/audit";
-import { Logger } from "@geekmidas/logger";
-import { InferStandardSchema } from "@geekmidas/schema";
-//#region src/publisher.d.ts
-export declare function publishConstructEvents<T extends EventPublisher<any> | undefined, OutSchema extends StandardSchemaV1 | undefined = undefined, TServiceName extends string = string, TServices extends Service[] = [], TAuditStorageServiceName extends string = string, TAuditStorage extends AuditStorage | undefined = undefined>(construct: Construct<Logger, TServiceName, T, OutSchema, TServices, TAuditStorageServiceName, TAuditStorage>, response: InferStandardSchema<OutSchema>, serviceDiscovery: ServiceDiscovery<any>, logger?: Logger): Promise<void>;
-//#endregion
 //#region src/endpoints/lazyAccessors.d.ts
 /**
  * Create a lazy header accessor for Hono.
@@ -56,5 +47,5 @@ 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 MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme };
+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 MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
 //# sourceMappingURL=index.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/publisher.ts","../../src/endpoints/lazyAccessors.ts","../../src/endpoints/surfaceEnv.ts"],"mappings":";;;;;;;;;;;;wBAgEsB,uBACrB,UAAU,iCACV,kBAAkB,0CAClB,sCACA,kBAAkB,gBAClB,kDACA,sBAAsB,sCAEtB,WAAW,UACV,QACA,cACA,GACA,WACA,WACA,0BACA,gBAED,UAAU,oBAAoB,YAC9B,kBAAkB,uBAClB,SAAQ,SAAyB;;;;;;;;wBCnElB,kBAAkB,GAAG,UAAU;;;;;;wBAqB/B,kBAAkB,GAAG,UAAU;;;;;wBAgC/B,wBACf,SAAS,wDACP;;;;;wBAoCa,wBACf,+BACA,mCACE;;;;wBAmHa,qBAAqB;;;;wBAUrB,qBAAqB;;;;;;;;;;wBC1MrB,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/endpoints/lazyAccessors.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;;;;;;;;;;wBC1MrB,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}

package/dist/endpoints/index.mjs

@@ -1,5 +1,6 @@
-import { a as createAuthorizer, i as BUILT_IN_SECURITY_SCHEMES, n as EndpointBuilder, o as getSecurityScheme, r as RLS_BYPASS, s as isBuiltInSecurityScheme, t as EndpointFactory } from "../EndpointFactory-B9HAjDAP.mjs";
-import { n as ResponseBuilder, r as NoAuthenticator, t as Endpoint } from "../Endpoint-DO332Dnm.mjs";
+import { a as createAuthorizer, i as BUILT_IN_SECURITY_SCHEMES, n as EndpointBuilder, o as getSecurityScheme, r as RLS_BYPASS, s as isBuiltInSecurityScheme, t as EndpointFactory } from "../EndpointFactory-BBdNeaGJ.mjs";
+import { i as publishConstructEvents } from "../functions-DCIfCRR-.mjs";
+import { n as ResponseBuilder, r as NoAuthenticator, t as Endpoint } from "../Endpoint-CQAeh1Rh.mjs";
 import { n as envParserFor, t as defaultEnvParser } from "../surfaceEnv-wMT5QzgZ.mjs";
-import { a as createHonoHeaders, i as createHonoCookies, l as publishConstructEvents, n as createApiGatewayHeaders, o as createNoopCookies, s as createNoopHeaders, t as createApiGatewayCookies } from "../lazyAccessors-BHtcqgz2.mjs";
+import { a as createHonoHeaders, i as createHonoCookies, n as createApiGatewayHeaders, o as createNoopCookies, s as createNoopHeaders, t as createApiGatewayCookies } from "../lazyAccessors-CFanua0O.mjs";
 export { BUILT_IN_SECURITY_SCHEMES, Endpoint, EndpointBuilder, EndpointFactory, NoAuthenticator, RLS_BYPASS, ResponseBuilder, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };

package/dist/external-api-DS3mujT5.d.mts

@@ -0,0 +1,86 @@
+import { t as StandardSchemaV1 } from "./index-CeEtxDmK.mjs";
+import { r as Consumable } from "./construct-interface-_3zgxzXl.mjs";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { Service } from "@geekmidas/services";
+//#region src/external-api.d.ts
+/** What a credentials schema yields. */
+type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {
+  /**
+   * Where it answers deployed: one URL for every stage, or one per stage
+   * name, with `default` for any stage not listed.
+   */
+  url: string | Readonly<Record<string, string>>;
+  /** What the stage's `<ID>_CREDENTIALS` must look like. */
+  credentials: TSchema;
+  /** What a handler is handed, built from where it answers and the credentials. */
+  client: (connection: {
+    url: string;
+    credentials: Value<TSchema>;
+  }) => TClient | Promise<TClient>;
+}
+declare class ExternalApi<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1, TClient = unknown> implements Consumable<TName, TClient> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, TClient>;
+  /** Read by both `declare()` and `connect()`, so the two cannot drift. */
+  private readonly keys;
+  /** The promise, so concurrent registrations share one client. */
+  private connected?;
+  constructor(id: ConstructName<TName>, options: ExternalApiOptions<TSchema, TClient>);
+  declare(): Declaration[];
+  private connect;
+}
+/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */
+interface FetchHandler {
+  fetch(request: Request): Response | Promise<Response>;
+}
+/**
+ * Marks a fake. A registered symbol, so a fake built by a second copy of this
+ * package — a linked workspace, two versions in a lockfile — is still one.
+ */
+declare const FAKE: unique symbol;
+/** What an external API's credentials look like going in, for a fake to supply. */
+type CredentialsOf<TApi> = TApi extends ExternalApi<string, infer TSchema, unknown> ? StandardSchemaV1.InferInput<TSchema> : unknown;
+/**
+ * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.
+ *
+ * `credentials` are what the fake accepts, and what a local or test stage is
+ * handed as `<ID>_CREDENTIALS` in place of the stage's own.
+ */
+type Fake = {
+  readonly [FAKE]: true;
+  readonly credentials: unknown;
+} & ({
+  readonly kind: 'app';
+  /** Served by gkm: in-process in a test, on its own port in `gkm dev`. */
+  readonly handler: FetchHandler;
+} | {
+  readonly kind: 'image';
+  /** The provider's own local server, run as a container. */
+  readonly image: string;
+  /** The port it listens on inside the container. */
+  readonly port: number;
+});
+/**
+ * Build the fake `test/fakes/<id>.ts` default-exports.
+ *
+ * Pass the API's type to have the credentials checked against its schema —
+ * `fake.app<typeof polar>(…)`.
+ */
+declare const fake: {
+  /** A working implementation of the API, kept beside the tests that use it. */
+  app<TApi = unknown>(handler: FetchHandler, options: {
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /** A local server the provider publishes — `stripe/stripe-mock`. */
+  image<TApi = unknown>(image: string, options: {
+    port: number;
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+declare function isFake(value: unknown): value is Fake;
+//#endregion
+export { fake as a, FetchHandler as i, ExternalApiOptions as n, isFake as o, Fake as r, ExternalApi as t };
+//# sourceMappingURL=external-api-DS3mujT5.d.mts.map

package/dist/external-api-DS3mujT5.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-DS3mujT5.d.mts","names":[],"sources":["../src/external-api.ts"],"mappings":";;;;;;KAmDK,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;UAEb,mBAAmB,gBAAgB,kBAAkB;;;;;EAKrE,cAAc,SAAS;;EAEvB,aAAa;;EAEb,SAAS;IACR;IACA,aAAa,MAAM;QACd,UAAU,QAAQ;;cAGZ,YACZ,+BACA,gBAAgB,mBAAmB,kBACnC,8BACY,WAAW,OAAO;mBAeZ;WAXT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;;mBAG9B;;UAGT;EAER,YACC,IAAI,cAAc,QACD,SAAS,mBAAmB,SAAS;EAoBvD,WAAW;UAWG;;;UAgBE;EAChB,MAAM,SAAS,UAAU,WAAW,QAAQ;;;;;;cAOvC;;KAGD,cAAc,QAClB,aAAa,0BAA0B,oBACpC,iBAAiB,WAAW;;;;;;;KASpB;YACD;WACD;;WAGE;;WAEA,SAAS;;WAGT;;WAEA;;WAEA;;;;;;;;cAUC;;EAEZ,IAAI,gBAAc,SACR,cAAY;IACV,aAAa,cAAc;MACpC;;EAUH,MAAM,gBAAc,eACN;IACF;IAAc,aAAa,cAAc;MAClD;;;iBAYY,OAAO,iBAAiB,SAAS"}

package/dist/external-api-LBfE-q3g.d.cts

@@ -0,0 +1,86 @@
+import { t as StandardSchemaV1 } from "./index-CeEtxDmK.cjs";
+import { r as Consumable } from "./construct-interface-_xi4BPN8.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+//#region src/external-api.d.ts
+/** What a credentials schema yields. */
+type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {
+  /**
+   * Where it answers deployed: one URL for every stage, or one per stage
+   * name, with `default` for any stage not listed.
+   */
+  url: string | Readonly<Record<string, string>>;
+  /** What the stage's `<ID>_CREDENTIALS` must look like. */
+  credentials: TSchema;
+  /** What a handler is handed, built from where it answers and the credentials. */
+  client: (connection: {
+    url: string;
+    credentials: Value<TSchema>;
+  }) => TClient | Promise<TClient>;
+}
+declare class ExternalApi<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1, TClient = unknown> implements Consumable<TName, TClient> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, TClient>;
+  /** Read by both `declare()` and `connect()`, so the two cannot drift. */
+  private readonly keys;
+  /** The promise, so concurrent registrations share one client. */
+  private connected?;
+  constructor(id: ConstructName<TName>, options: ExternalApiOptions<TSchema, TClient>);
+  declare(): Declaration[];
+  private connect;
+}
+/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */
+interface FetchHandler {
+  fetch(request: Request): Response | Promise<Response>;
+}
+/**
+ * Marks a fake. A registered symbol, so a fake built by a second copy of this
+ * package — a linked workspace, two versions in a lockfile — is still one.
+ */
+declare const FAKE: unique symbol;
+/** What an external API's credentials look like going in, for a fake to supply. */
+type CredentialsOf<TApi> = TApi extends ExternalApi<string, infer TSchema, unknown> ? StandardSchemaV1.InferInput<TSchema> : unknown;
+/**
+ * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.
+ *
+ * `credentials` are what the fake accepts, and what a local or test stage is
+ * handed as `<ID>_CREDENTIALS` in place of the stage's own.
+ */
+type Fake = {
+  readonly [FAKE]: true;
+  readonly credentials: unknown;
+} & ({
+  readonly kind: 'app';
+  /** Served by gkm: in-process in a test, on its own port in `gkm dev`. */
+  readonly handler: FetchHandler;
+} | {
+  readonly kind: 'image';
+  /** The provider's own local server, run as a container. */
+  readonly image: string;
+  /** The port it listens on inside the container. */
+  readonly port: number;
+});
+/**
+ * Build the fake `test/fakes/<id>.ts` default-exports.
+ *
+ * Pass the API's type to have the credentials checked against its schema —
+ * `fake.app<typeof polar>(…)`.
+ */
+declare const fake: {
+  /** A working implementation of the API, kept beside the tests that use it. */
+  app<TApi = unknown>(handler: FetchHandler, options: {
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /** A local server the provider publishes — `stripe/stripe-mock`. */
+  image<TApi = unknown>(image: string, options: {
+    port: number;
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+declare function isFake(value: unknown): value is Fake;
+//#endregion
+export { fake as a, FetchHandler as i, ExternalApiOptions as n, isFake as o, Fake as r, ExternalApi as t };
+//# sourceMappingURL=external-api-LBfE-q3g.d.cts.map

package/dist/external-api-LBfE-q3g.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-LBfE-q3g.d.cts","names":[],"sources":["../src/external-api.ts"],"mappings":";;;;;;KAmDK,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;UAEb,mBAAmB,gBAAgB,kBAAkB;;;;;EAKrE,cAAc,SAAS;;EAEvB,aAAa;;EAEb,SAAS;IACR;IACA,aAAa,MAAM;QACd,UAAU,QAAQ;;cAGZ,YACZ,+BACA,gBAAgB,mBAAmB,kBACnC,8BACY,WAAW,OAAO;mBAeZ;WAXT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;;mBAG9B;;UAGT;EAER,YACC,IAAI,cAAc,QACD,SAAS,mBAAmB,SAAS;EAoBvD,WAAW;UAWG;;;UAgBE;EAChB,MAAM,SAAS,UAAU,WAAW,QAAQ;;;;;;cAOvC;;KAGD,cAAc,QAClB,aAAa,0BAA0B,oBACpC,iBAAiB,WAAW;;;;;;;KASpB;YACD;WACD;;WAGE;;WAEA,SAAS;;WAGT;;WAEA;;WAEA;;;;;;;;cAUC;;EAEZ,IAAI,gBAAc,SACR,cAAY;IACV,aAAa,cAAc;MACpC;;EAUH,MAAM,gBAAc,eACN;IACF;IAAc,aAAa,cAAc;MAClD;;;iBAYY,OAAO,iBAAiB,SAAS"}

package/dist/external-api.cjs

@@ -0,0 +1,124 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_credential = require("./credential.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;
+			}
+		};
+	}
+	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);
+		return this.options.client({
+			url,
+			credentials
+		});
+	}
+};
+/**
+* Marks a fake. A registered symbol, so a fake built by a second copy of this
+* package — a linked workspace, two versions in a lockfile — is still one.
+*/
+const FAKE = Symbol.for("@geekmidas/constructs/fake");
+/**
+* Build the fake `test/fakes/<id>.ts` default-exports.
+*
+* Pass the API's type to have the credentials checked against its schema —
+* `fake.app<typeof polar>(…)`.
+*/
+const fake = {
+	/** A working implementation of the API, kept beside the tests that use it. */
+	app(handler, options) {
+		return {
+			[FAKE]: true,
+			kind: "app",
+			handler,
+			credentials: options.credentials
+		};
+	},
+	/** A local server the provider publishes — `stripe/stripe-mock`. */
+	image(image, options) {
+		return {
+			[FAKE]: true,
+			kind: "image",
+			image,
+			port: options.port,
+			credentials: options.credentials
+		};
+	}
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+function isFake(value) {
+	return typeof value === "object" && value !== null && value[FAKE] === true;
+}
+//#endregion
+exports.ExternalApi = ExternalApi;
+exports.fake = fake;
+exports.isFake = 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"],"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';\n\n/** What a credentials schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\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: string | Readonly<Record<string, string>>;\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\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\turl: this.options.url,\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\treturn this.options.client({ url, credentials });\n\t}\n}\n\n/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */\nexport interface FetchHandler {\n\tfetch(request: Request): Response | Promise<Response>;\n}\n\n/**\n * Marks a fake. A registered symbol, so a fake built by a second copy of this\n * package — a linked workspace, two versions in a lockfile — is still one.\n */\nconst FAKE = Symbol.for('@geekmidas/constructs/fake');\n\n/** What an external API's credentials look like going in, for a fake to supply. */\ntype CredentialsOf<TApi> =\n\tTApi extends ExternalApi<string, infer TSchema, unknown>\n\t\t? StandardSchemaV1.InferInput<TSchema>\n\t\t: unknown;\n\n/**\n * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.\n *\n * `credentials` are what the fake accepts, and what a local or test stage is\n * handed as `<ID>_CREDENTIALS` in place of the stage's own.\n */\nexport type Fake = {\n\treadonly [FAKE]: true;\n\treadonly credentials: unknown;\n} & (\n\t| {\n\t\t\treadonly kind: 'app';\n\t\t\t/** Served by gkm: in-process in a test, on its own port in `gkm dev`. */\n\t\t\treadonly handler: FetchHandler;\n\t  }\n\t| {\n\t\t\treadonly kind: 'image';\n\t\t\t/** The provider's own local server, run as a container. */\n\t\t\treadonly image: string;\n\t\t\t/** The port it listens on inside the container. */\n\t\t\treadonly port: number;\n\t  }\n);\n\n/**\n * Build the fake `test/fakes/<id>.ts` default-exports.\n *\n * Pass the API's type to have the credentials checked against its schema —\n * `fake.app<typeof polar>(…)`.\n */\nexport const fake = {\n\t/** A working implementation of the API, kept beside the tests that use it. */\n\tapp<TApi = unknown>(\n\t\thandler: FetchHandler,\n\t\toptions: { credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'app',\n\t\t\thandler,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n\n\t/** A local server the provider publishes — `stripe/stripe-mock`. */\n\timage<TApi = unknown>(\n\t\timage: string,\n\t\toptions: { port: number; credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'image',\n\t\t\timage,\n\t\t\tport: options.port,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n};\n\n/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */\nexport function isFake(value: unknown): value is Fake {\n\treturn (\n\t\ttypeof value === 'object' &&\n\t\tvalue !== null &&\n\t\t(value as { [FAKE]?: unknown })[FAKE] === true\n\t);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,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;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,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,OAAO,KAAK,QAAQ,OAAO;GAAE;GAAK;EAAY,CAAC;CAChD;AACD;;;;;AAWA,MAAM,OAAO,OAAO,IAAI,4BAA4B;;;;;;;AAsCpD,MAAa,OAAO;;CAEnB,IACC,SACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,aAAa,QAAQ;EACtB;CACD;;CAGA,MACC,OACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,MAAM,QAAQ;GACd,aAAa,QAAQ;EACtB;CACD;AACD;;AAGA,SAAgB,OAAO,OAA+B;CACrD,OACC,OAAO,UAAU,YACjB,UAAU,QACT,MAA+B,UAAU;AAE5C"}

package/dist/external-api.d.cts

@@ -0,0 +1,2 @@
+import { a as fake, i as FetchHandler, n as ExternalApiOptions, o as isFake, r as Fake, t as ExternalApi } from "./external-api-LBfE-q3g.cjs";
+export { ExternalApi, ExternalApiOptions, Fake, FetchHandler, fake, isFake };

package/dist/external-api.d.mts

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

package/dist/external-api.mjs

@@ -0,0 +1,121 @@
+import { readCredentials } from "./credential.mjs";
+import { canonicalId, provideKey, serviceKey } from "@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 = canonicalId(id);
+		this.id = canonical;
+		this.keys = {
+			url: provideKey(canonical, "url"),
+			credentials: provideKey(canonical, "credentials")
+		};
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (registerOptions) => {
+				this.connected ??= this.connect(registerOptions);
+				return this.connected;
+			}
+		};
+	}
+	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 readCredentials(this.id, this.keys.credentials, this.options.credentials, options.envParser);
+		return this.options.client({
+			url,
+			credentials
+		});
+	}
+};
+/**
+* Marks a fake. A registered symbol, so a fake built by a second copy of this
+* package — a linked workspace, two versions in a lockfile — is still one.
+*/
+const FAKE = Symbol.for("@geekmidas/constructs/fake");
+/**
+* Build the fake `test/fakes/<id>.ts` default-exports.
+*
+* Pass the API's type to have the credentials checked against its schema —
+* `fake.app<typeof polar>(…)`.
+*/
+const fake = {
+	/** A working implementation of the API, kept beside the tests that use it. */
+	app(handler, options) {
+		return {
+			[FAKE]: true,
+			kind: "app",
+			handler,
+			credentials: options.credentials
+		};
+	},
+	/** A local server the provider publishes — `stripe/stripe-mock`. */
+	image(image, options) {
+		return {
+			[FAKE]: true,
+			kind: "image",
+			image,
+			port: options.port,
+			credentials: options.credentials
+		};
+	}
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+function isFake(value) {
+	return typeof value === "object" && value !== null && value[FAKE] === true;
+}
+//#endregion
+export { ExternalApi, fake, isFake };
+
+//# sourceMappingURL=external-api.mjs.map

package/dist/external-api.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api.mjs","names":[],"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';\n\n/** What a credentials schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\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: string | Readonly<Record<string, string>>;\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\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\turl: this.options.url,\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\treturn this.options.client({ url, credentials });\n\t}\n}\n\n/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */\nexport interface FetchHandler {\n\tfetch(request: Request): Response | Promise<Response>;\n}\n\n/**\n * Marks a fake. A registered symbol, so a fake built by a second copy of this\n * package — a linked workspace, two versions in a lockfile — is still one.\n */\nconst FAKE = Symbol.for('@geekmidas/constructs/fake');\n\n/** What an external API's credentials look like going in, for a fake to supply. */\ntype CredentialsOf<TApi> =\n\tTApi extends ExternalApi<string, infer TSchema, unknown>\n\t\t? StandardSchemaV1.InferInput<TSchema>\n\t\t: unknown;\n\n/**\n * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.\n *\n * `credentials` are what the fake accepts, and what a local or test stage is\n * handed as `<ID>_CREDENTIALS` in place of the stage's own.\n */\nexport type Fake = {\n\treadonly [FAKE]: true;\n\treadonly credentials: unknown;\n} & (\n\t| {\n\t\t\treadonly kind: 'app';\n\t\t\t/** Served by gkm: in-process in a test, on its own port in `gkm dev`. */\n\t\t\treadonly handler: FetchHandler;\n\t  }\n\t| {\n\t\t\treadonly kind: 'image';\n\t\t\t/** The provider's own local server, run as a container. */\n\t\t\treadonly image: string;\n\t\t\t/** The port it listens on inside the container. */\n\t\t\treadonly port: number;\n\t  }\n);\n\n/**\n * Build the fake `test/fakes/<id>.ts` default-exports.\n *\n * Pass the API's type to have the credentials checked against its schema —\n * `fake.app<typeof polar>(…)`.\n */\nexport const fake = {\n\t/** A working implementation of the API, kept beside the tests that use it. */\n\tapp<TApi = unknown>(\n\t\thandler: FetchHandler,\n\t\toptions: { credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'app',\n\t\t\thandler,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n\n\t/** A local server the provider publishes — `stripe/stripe-mock`. */\n\timage<TApi = unknown>(\n\t\timage: string,\n\t\toptions: { port: number; credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'image',\n\t\t\timage,\n\t\t\tport: options.port,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n};\n\n/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */\nexport function isFake(value: unknown): value is Fake {\n\treturn (\n\t\ttypeof value === 'object' &&\n\t\tvalue !== null &&\n\t\t(value as { [FAKE]?: unknown })[FAKE] === true\n\t);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,IAAa,cAAb,MAKA;CAcmB;CAXlB;CACA;;CAGA;;CAGA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO;GACX,KAAK,WAAW,WAAW,KAAK;GAChC,aAAa,WAAW,WAAW,aAAa;EACjD;EAGA,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,oBAAoB;IAC9B,KAAK,cAAc,KAAK,QAAQ,eAAe;IAC/C,OAAO,KAAK;GACb;EACD;CACD;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,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,MAAM,gBACzB,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,aACb,QAAQ,SACT;EAEA,OAAO,KAAK,QAAQ,OAAO;GAAE;GAAK;EAAY,CAAC;CAChD;AACD;;;;;AAWA,MAAM,OAAO,OAAO,IAAI,4BAA4B;;;;;;;AAsCpD,MAAa,OAAO;;CAEnB,IACC,SACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,aAAa,QAAQ;EACtB;CACD;;CAGA,MACC,OACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,MAAM,QAAQ;GACd,aAAa,QAAQ;EACtB;CACD;AACD;;AAGA,SAAgB,OAAO,OAA+B;CACrD,OACC,OAAO,UAAU,YACjB,UAAU,QACT,MAA+B,UAAU;AAE5C"}