@geekmidas/constructs 10.0.0-alpha.102 → 10.0.0-alpha.104

package/dist/credential.cjs

@@ -1,156 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let _geekmidas_manifest = require("@geekmidas/manifest");
-let _geekmidas_schema_parser = require("@geekmidas/schema/parser");
-//#region src/credential.ts
-/**
-* `Credential` — a third-party credential with a shape.
-*
-* The answer to the design's first open question, "where does `Secret` sit?".
-* It sits beside a secret rather than replacing it, because the two differ by
-* *lifecycle* and that is the only difference worth two kinds for: a secret is
-* generated and rotated by the platform and is one opaque string, while a
-* credential is issued by someone else, arrives with several fields, and is
-* worth validating on the way in.
-*
-* ```ts
-* export const stripe = new Credential('Stripe', {
-*   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),
-* });
-*
-* // in a handler — no await, already parsed and validated
-* services.stripe.secretKey
-* ```
-*
-* **Nothing about it is async at the call site**, which is the part that looks
-* like it should be hard and is not. `Service.register()` may return a promise
-* and `ServiceDiscovery` awaits every one before a handler runs, so fetching a
-* value and validating it — including when a StandardSchema's `~standard.validate`
-* returns a promise of its own — both happen inside that existing seam.
-*
-* **One key holding JSON, not one key per field.** That is the shape a secret
-* manager stores, and it is the only shape that works with an arbitrary
-* StandardSchema: the spec has no introspection API, so enumerating a schema's
-* fields means reaching into one library's internals (`.shape`) and being wrong
-* for every other.
-*/
-var Credential = class {
-	options;
-	id;
-	service;
-	/**
-	* Declared once and read by both `declare()` and `connect()`, so the key the
-	* target publishes and the key the client reads cannot drift.
-	*/
-	keys;
-	/**
-	* The resolved value, held as the *promise* rather than the value.
-	*
-	* Caching the promise is what makes two concurrent registrations share one
-	* resolution: caching the value would let both start before either finished,
-	* which is a duplicated fetch every cold start rather than never.
-	*/
-	resolved;
-	constructor(id, options) {
-		this.options = options;
-		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
-		this.id = canonical;
-		this.keys = { credentials: (0, _geekmidas_manifest.provideKey)(canonical, "credentials") };
-		this.service = {
-			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
-			register: (registerOptions) => this.connect(registerOptions)
-		};
-	}
-	/**
-	* 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.schema;
-	}
-	declare() {
-		return [{
-			kind: "credential",
-			id: this.id,
-			provides: [this.keys.credentials]
-		}];
-	}
-	connect(options) {
-		if (this.options.refresh) return this.resolve(options);
-		this.resolved ??= this.resolve(options);
-		return this.resolved;
-	}
-	resolve(options) {
-		return readCredentials(this.id, this.keys.credentials, this.options.schema, options.envParser);
-	}
-};
-/**
-* A credentials key, read and validated against its schema.
-*
-* Shared with every construct that holds a third party's credentials — an
-* `ExternalApi` reads its own the same way — so the shape a stage stores and
-* the error a bad value raises are the same everywhere.
-*
-* @throws {MalformedCredential} when the value is not what the schema says.
-*/
-async function readCredentials(id, key, schema, envParser) {
-	const { raw } = envParser.create((get) => ({ raw: get(key).string() })).parse();
-	try {
-		return await (0, _geekmidas_schema_parser.parseSchema)(schema, decodeCredentials(raw));
-	} catch (issues) {
-		throw new MalformedCredential(id, key, issues);
-	}
-}
-/**
-* The raw environment value as the thing the schema should see.
-*
-* JSON when it is JSON, and the string itself when it is not — a credential
-* with a single opaque field is ordinary, and requiring `"…"` around it would
-* be ceremony that every operator setting one by hand would get wrong once.
-*
-* Exported so a tool checking a value before it is stored reads it exactly as
-* the process that uses it will.
-*/
-function decodeCredentials(raw) {
-	const value = raw.startsWith(JSON_SCHEME) ? raw.slice(JSON_SCHEME.length) : raw;
-	try {
-		return JSON.parse(value);
-	} catch {
-		return value;
-	}
-}
-/**
-* The explicit form, for the case a credential legitimately *is* a JSON string
-* and must not be parsed into an object. Rare, and cheaper to support than to
-* explain.
-*/
-const JSON_SCHEME = "json:";
-/** A credential was set, and is not what its schema says it should be. */
-var MalformedCredential = class extends Error {
-	id;
-	key;
-	issues;
-	constructor(id, key, issues) {
-		super(`${key} is not a valid ${id} credential. It is validated where it is read, so this is the value that is set rather than the code that uses it: ${describe(issues)}`);
-		this.id = id;
-		this.key = key;
-		this.issues = issues;
-		this.name = "MalformedCredential";
-	}
-};
-/** StandardSchema issues as one line. */
-function describe(issues) {
-	if (!Array.isArray(issues)) return String(issues);
-	return issues.map((issue) => {
-		const path = issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".");
-		return path ? `${path}: ${issue.message}` : issue.message;
-	}).join("; ");
-}
-//#endregion
-exports.Credential = Credential;
-exports.MalformedCredential = MalformedCredential;
-exports.decodeCredentials = decodeCredentials;
-exports.readCredentials = readCredentials;
-
-//# sourceMappingURL=credential.cjs.map
+const require_credential = require("./credential-DYymbp_7.cjs");
+exports.Credential = require_credential.Credential;
+exports.MalformedCredential = require_credential.MalformedCredential;
+exports.decodeCredentials = require_credential.decodeCredentials;
+exports.fake = require_credential.fake;
+exports.isFake = require_credential.isFake;
+exports.readCredentials = require_credential.readCredentials;

package/dist/credential.d.cts

@@ -1,86 +1,2 @@
-import { t as StandardSchemaV1 } from "./index-CeEtxDmK.cjs";
-import { r as Consumable } from "./construct-interface-B1AfqRl4.cjs";
-import { Service, ServiceRegisterOptions } from "@geekmidas/services";
-import { ConstructName, Declaration } from "@geekmidas/manifest";
-//#region src/credential.d.ts
-/** What a credential's schema yields. */
-type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
-export interface CredentialOptions<TSchema extends StandardSchemaV1> {
-  /**
-   * What the credential must look like.
-   *
-   * Validated at registration, so a malformed or half-set credential fails
-   * when the process starts rather than on the first request that needs the
-   * one field somebody forgot.
-   */
-  schema: TSchema;
-  /**
-   * Re-resolve on every registration instead of once per process.
-   *
-   * Off by default: a credential is resolved once and reused, because the
-   * alternative is a fetch on every request. The cost of that default is that
-   * a rotated credential needs a restart, which is the right trade for a value
-   * that changes a few times a year — and this is the escape hatch for when it
-   * is not.
-   */
-  refresh?: boolean;
-}
-export declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value<TSchema>> {
-  private readonly options;
-  readonly id: TName;
-  readonly service: Service<Uncapitalize<TName>, Value<TSchema>>;
-  /**
-   * Declared once and read by both `declare()` and `connect()`, so the key the
-   * target publishes and the key the client reads cannot drift.
-   */
-  private readonly keys;
-  /**
-   * The resolved value, held as the *promise* rather than the value.
-   *
-   * Caching the promise is what makes two concurrent registrations share one
-   * resolution: caching the value would let both start before either finished,
-   * which is a duplicated fetch every cold start rather than never.
-   */
-  private resolved?;
-  constructor(id: ConstructName<TName>, options: CredentialOptions<TSchema>);
-  /**
-   * 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(): TSchema;
-  declare(): Declaration[];
-  private connect;
-  private resolve;
-}
-/**
- * A credentials key, read and validated against its schema.
- *
- * Shared with every construct that holds a third party's credentials — an
- * `ExternalApi` reads its own the same way — so the shape a stage stores and
- * the error a bad value raises are the same everywhere.
- *
- * @throws {MalformedCredential} when the value is not what the schema says.
- */
-export declare function readCredentials<TSchema extends StandardSchemaV1>(id: string, key: string, schema: TSchema, envParser: ServiceRegisterOptions['envParser']): Promise<Value<TSchema>>;
-/**
- * The raw environment value as the thing the schema should see.
- *
- * JSON when it is JSON, and the string itself when it is not — a credential
- * with a single opaque field is ordinary, and requiring `"…"` around it would
- * be ceremony that every operator setting one by hand would get wrong once.
- *
- * Exported so a tool checking a value before it is stored reads it exactly as
- * the process that uses it will.
- */
-export declare function decodeCredentials(raw: string): unknown;
-/** A credential was set, and is not what its schema says it should be. */
-export declare class MalformedCredential extends Error {
-  readonly id: string;
-  readonly key: string;
-  readonly issues: unknown;
-  constructor(id: string, key: string, issues: unknown);
-}
-//#endregion
-//# sourceMappingURL=credential.d.cts.map
+import { c as Credential, d as decodeCredentials, f as readCredentials, i as isFake, l as CredentialOptions, r as fake, t as Fake, u as MalformedCredential } from "./fake-Dvion_Fh.cjs";
+export { Credential, CredentialOptions, type Fake, MalformedCredential, decodeCredentials, fake, isFake, readCredentials };

package/dist/credential.d.mts

@@ -1,86 +1,2 @@
-import { t as StandardSchemaV1 } from "./index-CeEtxDmK.mjs";
-import { r as Consumable } from "./construct-interface-DluK3_da.mjs";
-import { ConstructName, Declaration } from "@geekmidas/manifest";
-import { Service, ServiceRegisterOptions } from "@geekmidas/services";
-//#region src/credential.d.ts
-/** What a credential's schema yields. */
-type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
-export interface CredentialOptions<TSchema extends StandardSchemaV1> {
-  /**
-   * What the credential must look like.
-   *
-   * Validated at registration, so a malformed or half-set credential fails
-   * when the process starts rather than on the first request that needs the
-   * one field somebody forgot.
-   */
-  schema: TSchema;
-  /**
-   * Re-resolve on every registration instead of once per process.
-   *
-   * Off by default: a credential is resolved once and reused, because the
-   * alternative is a fetch on every request. The cost of that default is that
-   * a rotated credential needs a restart, which is the right trade for a value
-   * that changes a few times a year — and this is the escape hatch for when it
-   * is not.
-   */
-  refresh?: boolean;
-}
-export declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value<TSchema>> {
-  private readonly options;
-  readonly id: TName;
-  readonly service: Service<Uncapitalize<TName>, Value<TSchema>>;
-  /**
-   * Declared once and read by both `declare()` and `connect()`, so the key the
-   * target publishes and the key the client reads cannot drift.
-   */
-  private readonly keys;
-  /**
-   * The resolved value, held as the *promise* rather than the value.
-   *
-   * Caching the promise is what makes two concurrent registrations share one
-   * resolution: caching the value would let both start before either finished,
-   * which is a duplicated fetch every cold start rather than never.
-   */
-  private resolved?;
-  constructor(id: ConstructName<TName>, options: CredentialOptions<TSchema>);
-  /**
-   * 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(): TSchema;
-  declare(): Declaration[];
-  private connect;
-  private resolve;
-}
-/**
- * A credentials key, read and validated against its schema.
- *
- * Shared with every construct that holds a third party's credentials — an
- * `ExternalApi` reads its own the same way — so the shape a stage stores and
- * the error a bad value raises are the same everywhere.
- *
- * @throws {MalformedCredential} when the value is not what the schema says.
- */
-export declare function readCredentials<TSchema extends StandardSchemaV1>(id: string, key: string, schema: TSchema, envParser: ServiceRegisterOptions['envParser']): Promise<Value<TSchema>>;
-/**
- * The raw environment value as the thing the schema should see.
- *
- * JSON when it is JSON, and the string itself when it is not — a credential
- * with a single opaque field is ordinary, and requiring `"…"` around it would
- * be ceremony that every operator setting one by hand would get wrong once.
- *
- * Exported so a tool checking a value before it is stored reads it exactly as
- * the process that uses it will.
- */
-export declare function decodeCredentials(raw: string): unknown;
-/** A credential was set, and is not what its schema says it should be. */
-export declare class MalformedCredential extends Error {
-  readonly id: string;
-  readonly key: string;
-  readonly issues: unknown;
-  constructor(id: string, key: string, issues: unknown);
-}
-//#endregion
-//# sourceMappingURL=credential.d.mts.map
+import { c as Credential, d as decodeCredentials, f as readCredentials, i as isFake, l as CredentialOptions, r as fake, t as Fake, u as MalformedCredential } from "./fake-BcHTPz7N.mjs";
+export { Credential, CredentialOptions, type Fake, MalformedCredential, decodeCredentials, fake, isFake, readCredentials };

package/dist/credential.mjs

@@ -1,152 +1,2 @@
-import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
-import { parseSchema } from "@geekmidas/schema/parser";
-//#region src/credential.ts
-/**
-* `Credential` — a third-party credential with a shape.
-*
-* The answer to the design's first open question, "where does `Secret` sit?".
-* It sits beside a secret rather than replacing it, because the two differ by
-* *lifecycle* and that is the only difference worth two kinds for: a secret is
-* generated and rotated by the platform and is one opaque string, while a
-* credential is issued by someone else, arrives with several fields, and is
-* worth validating on the way in.
-*
-* ```ts
-* export const stripe = new Credential('Stripe', {
-*   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),
-* });
-*
-* // in a handler — no await, already parsed and validated
-* services.stripe.secretKey
-* ```
-*
-* **Nothing about it is async at the call site**, which is the part that looks
-* like it should be hard and is not. `Service.register()` may return a promise
-* and `ServiceDiscovery` awaits every one before a handler runs, so fetching a
-* value and validating it — including when a StandardSchema's `~standard.validate`
-* returns a promise of its own — both happen inside that existing seam.
-*
-* **One key holding JSON, not one key per field.** That is the shape a secret
-* manager stores, and it is the only shape that works with an arbitrary
-* StandardSchema: the spec has no introspection API, so enumerating a schema's
-* fields means reaching into one library's internals (`.shape`) and being wrong
-* for every other.
-*/
-var Credential = class {
-	options;
-	id;
-	service;
-	/**
-	* Declared once and read by both `declare()` and `connect()`, so the key the
-	* target publishes and the key the client reads cannot drift.
-	*/
-	keys;
-	/**
-	* The resolved value, held as the *promise* rather than the value.
-	*
-	* Caching the promise is what makes two concurrent registrations share one
-	* resolution: caching the value would let both start before either finished,
-	* which is a duplicated fetch every cold start rather than never.
-	*/
-	resolved;
-	constructor(id, options) {
-		this.options = options;
-		const canonical = canonicalId(id);
-		this.id = canonical;
-		this.keys = { credentials: provideKey(canonical, "credentials") };
-		this.service = {
-			serviceName: serviceKey(canonical),
-			register: (registerOptions) => this.connect(registerOptions)
-		};
-	}
-	/**
-	* 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.schema;
-	}
-	declare() {
-		return [{
-			kind: "credential",
-			id: this.id,
-			provides: [this.keys.credentials]
-		}];
-	}
-	connect(options) {
-		if (this.options.refresh) return this.resolve(options);
-		this.resolved ??= this.resolve(options);
-		return this.resolved;
-	}
-	resolve(options) {
-		return readCredentials(this.id, this.keys.credentials, this.options.schema, options.envParser);
-	}
-};
-/**
-* A credentials key, read and validated against its schema.
-*
-* Shared with every construct that holds a third party's credentials — an
-* `ExternalApi` reads its own the same way — so the shape a stage stores and
-* the error a bad value raises are the same everywhere.
-*
-* @throws {MalformedCredential} when the value is not what the schema says.
-*/
-async function readCredentials(id, key, schema, envParser) {
-	const { raw } = envParser.create((get) => ({ raw: get(key).string() })).parse();
-	try {
-		return await parseSchema(schema, decodeCredentials(raw));
-	} catch (issues) {
-		throw new MalformedCredential(id, key, issues);
-	}
-}
-/**
-* The raw environment value as the thing the schema should see.
-*
-* JSON when it is JSON, and the string itself when it is not — a credential
-* with a single opaque field is ordinary, and requiring `"…"` around it would
-* be ceremony that every operator setting one by hand would get wrong once.
-*
-* Exported so a tool checking a value before it is stored reads it exactly as
-* the process that uses it will.
-*/
-function decodeCredentials(raw) {
-	const value = raw.startsWith(JSON_SCHEME) ? raw.slice(JSON_SCHEME.length) : raw;
-	try {
-		return JSON.parse(value);
-	} catch {
-		return value;
-	}
-}
-/**
-* The explicit form, for the case a credential legitimately *is* a JSON string
-* and must not be parsed into an object. Rare, and cheaper to support than to
-* explain.
-*/
-const JSON_SCHEME = "json:";
-/** A credential was set, and is not what its schema says it should be. */
-var MalformedCredential = class extends Error {
-	id;
-	key;
-	issues;
-	constructor(id, key, issues) {
-		super(`${key} is not a valid ${id} credential. It is validated where it is read, so this is the value that is set rather than the code that uses it: ${describe(issues)}`);
-		this.id = id;
-		this.key = key;
-		this.issues = issues;
-		this.name = "MalformedCredential";
-	}
-};
-/** StandardSchema issues as one line. */
-function describe(issues) {
-	if (!Array.isArray(issues)) return String(issues);
-	return issues.map((issue) => {
-		const path = issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".");
-		return path ? `${path}: ${issue.message}` : issue.message;
-	}).join("; ");
-}
-//#endregion
-export { Credential, MalformedCredential, decodeCredentials, readCredentials };
-
-//# sourceMappingURL=credential.mjs.map
+import { a as fake, i as readCredentials, n as MalformedCredential, o as isFake, r as decodeCredentials, t as Credential } from "./credential-DfSAOOdY.mjs";
+export { Credential, MalformedCredential, decodeCredentials, fake, isFake, readCredentials };

package/dist/external-api.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_credential = require("./credential.cjs");
+const require_credential = require("./credential-DYymbp_7.cjs");
 const require_tracing = require("./tracing-DPMidF_r.cjs");
 let _geekmidas_manifest = require("@geekmidas/manifest");
 //#region src/external-api.ts
@@ -98,45 +98,9 @@ function hostOf(url) {
 		return url;
 	}
 }
-/**
-* 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;
+exports.fake = require_credential.fake;
+exports.isFake = require_credential.isFake;
 
 //# sourceMappingURL=external-api.cjs.map

package/dist/external-api.cjs.map

@@ -1 +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\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;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"}
+{"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

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

package/dist/external-api.d.mts

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

package/dist/external-api.mjs

@@ -1,4 +1,4 @@
-import { readCredentials } from "./credential.mjs";
+import { a as fake, i as readCredentials, o as isFake } from "./credential-DfSAOOdY.mjs";
 import { r as traceClient } from "./tracing-CxaZ98IB.mjs";
 import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
 //#region src/external-api.ts
@@ -97,42 +97,6 @@ function hostOf(url) {
 		return url;
 	}
 }
-/**
-* 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 };