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

package/dist/external-api.mjs

@@ -0,0 +1,103 @@
+import { a as fake, i as readCredentials, o as isFake } from "./credential-DfSAOOdY.mjs";
+import { i as traceClient } from "./tracing-Bbj1uoFJ.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;
+			}
+		};
+	}
+	/**
+	* What the stage's `<ID>_CREDENTIALS` must look like — the schema the value
+	* is validated against where it is read. Public so a tool setting the value
+	* (`gkm secrets:add`) can check it, and describe its fields, before it is
+	* stored rather than at the first request.
+	*/
+	get credentialsSchema() {
+		return this.options.credentials;
+	}
+	declare() {
+		return [{
+			kind: "external-api",
+			id: this.id,
+			url: this.options.url,
+			provides: [this.keys.url, this.keys.credentials]
+		}];
+	}
+	async connect(options) {
+		const { url } = options.envParser.create((get) => ({ url: get(this.keys.url).string() })).parse();
+		const credentials = await readCredentials(this.id, this.keys.credentials, this.options.credentials, options.envParser);
+		const client = await this.options.client({
+			url,
+			credentials
+		});
+		return traceClient(this.id, client, { "server.address": hostOf(url) });
+	}
+};
+function hostOf(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return url;
+	}
+}
+//#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';\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,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;;;;;;;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,MAAM,gBACzB,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,aACb,QAAQ,SACT;EAEA,MAAM,SAAS,MAAM,KAAK,QAAQ,OAAO;GAAE;GAAK;EAAY,CAAC;EAG7D,OAAO,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/fake-B7rvi4Qp.d.cts

@@ -0,0 +1,201 @@
+import { n as StandardSchemaV1 } from "./index-DdRjYhiJ.cjs";
+import { r as Consumable } from "./construct-interface-B1AfqRl4.cjs";
+import { n as DeployedStage, r as LocalStage } from "./stages-BSCF19o2.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$1<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+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;
+}
+declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value$1<TSchema>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Value$1<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.
+ */
+declare function readCredentials<TSchema extends StandardSchemaV1>(id: string, key: string, schema: TSchema, envParser: ServiceRegisterOptions['envParser']): Promise<Value$1<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.
+ */
+declare function decodeCredentials(raw: string): unknown;
+/** A credential was set, and is not what its schema says it should be. */
+declare class MalformedCredential extends Error {
+  readonly id: string;
+  readonly key: string;
+  readonly issues: unknown;
+  constructor(id: string, key: string, issues: unknown);
+}
+//#endregion
+//#region src/external-api.d.ts
+/** What a credentials schema yields. */
+type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+/**
+ * Where an external API answers: one URL for every stage, or one per stage
+ * name with `default` for any stage not listed.
+ *
+ * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,
+ * so a key that names no stage — `prodution` — is a type error rather than a
+ * URL nothing reads. Without the file any key goes, as before.
+ */
+type ExternalApiUrl = string | (string extends LocalStage | DeployedStage ? Readonly<Record<string, string>> : { readonly [S in LocalStage | DeployedStage]?: string; } & {
+  readonly default?: string;
+});
+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: ExternalApiUrl;
+  /** 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>);
+  /**
+   * 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;
+}
+//#endregion
+//#region src/fake.d.ts
+/**
+ * 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;
+/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */
+interface FetchHandler {
+  fetch(request: Request): Response | Promise<Response>;
+}
+/**
+ * What a construct's credentials look like going in, for a fake to supply —
+ * an external API's `credentials` schema, or a credential's `schema`.
+ */
+type CredentialsOf<TConstruct> = TConstruct extends ExternalApi<string, infer TSchema, unknown> ? StandardSchemaV1.InferInput<TSchema> : TConstruct extends Credential<string, infer TSchema> ? StandardSchemaV1.InferInput<TSchema> : unknown;
+/**
+ * A third party's stand-in, as `test/fakes/<id>.ts` default-exports it.
+ *
+ * `credentials` are what a local or test stage is handed as `<ID>_CREDENTIALS`
+ * in place of the stage's own: what an external API's fake accepts, or a
+ * credential's test value.
+ */
+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;
+} | {
+  /** A `Credential`'s test value — nothing to serve. */
+  readonly kind: 'credential';
+});
+/**
+ * Build the fake `test/fakes/<id>.ts` default-exports.
+ *
+ * Pass the construct's type to have the value checked against its schema —
+ * `fake.app<typeof polar>(…)`, `fake.credential<typeof stripe>(…)`.
+ */
+declare const fake: {
+  /** A working implementation of an external API, kept beside the tests that use it. */
+  app<TApi = unknown>(handler: FetchHandler, options: {
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /** A local server an external API's provider publishes — `stripe/stripe-mock`. */
+  image<TApi = unknown>(image: string, options: {
+    port: number;
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /**
+   * A `Credential`'s value on the test stage and under `gkm dev --fake`, as
+   * its schema takes it — a string, or the object a JSON credential holds.
+   * It is validated where it is read, like the real one.
+   */
+  credential<TCredential = unknown>(credentials: CredentialsOf<TCredential>): 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 { ExternalApi as a, Credential as c, decodeCredentials as d, readCredentials as f, isFake as i, CredentialOptions as l, FetchHandler as n, ExternalApiOptions as o, fake as r, ExternalApiUrl as s, Fake as t, MalformedCredential as u };
+//# sourceMappingURL=fake-B7rvi4Qp.d.cts.map

package/dist/fake-B7rvi4Qp.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-B7rvi4Qp.d.cts","names":["Value"],"sources":["../src/credential.ts","../src/external-api.ts","../src/fake.ts"],"mappings":";;;;;;;KAiEKA,QAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;UAEb,kBAAkB,gBAAgB;;;;;;;;EAQlD,QAAQ;;;;;;;;;;EAUR;;cAGY,WACZ,+BACA,gBAAgB,mBAAmB,6BACvB,WAAW,OAAOA,QAAM;mBA6BlB;WApBT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQA,QAAM;;;;;mBAMpC;;;;;;;;UAST;EAER,YACC,IAAI,cAAc,QACD,SAAS,kBAAkB;;;;;;;MAoBzC,qBAAqB;EAIzB,WAAW;UAUH;UAQA;;;;;;;;;;;iBAmBa,gBAAgB,gBAAgB,kBACrD,YACA,aACA,QAAQ,SACR,WAAW,sCACT,QAAQA,QAAM;;;;;;;;;;;iBAsBD,kBAAkB;;cAoBrB,4BAA4B;WAE9B;WACA;WACA;EAHV,YACU,YACA,aACA;;;;;KCpLN,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;;;;;;;;;KAUlB,0CAEO,aAAa,gBAC3B,SAAS,sCACG,KAAK,aAAa;WACrB;;UAGG,mBAAmB,gBAAgB,kBAAkB;;;;;EAKrE,KAAK;;EAEL,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;;;;;;;MA0BnD,qBAAqB;EAIzB,WAAW;UAaG;;;;;;;;cCjHT;;UAGW;EAChB,MAAM,SAAS,UAAU,WAAW,QAAQ;;;;;;KAOxC,cAAc,cAClB,mBAAmB,0BAA0B,oBAC1C,iBAAiB,WAAW,WAC5B,mBAAmB,yBAAyB,WAC3C,iBAAiB,WAAW;;;;;;;;KAUrB;YACD;WACD;;WAGE;;WAEA,SAAS;;WAGT;;WAEA;;WAEA;;;WAIA;;;;;;;;cAUC;;EAEZ,IAAI,gBAAc,SACR,cAAY;IACV,aAAa,cAAc;MACpC;;EAUH,MAAM,gBAAc,eACN;IACF;IAAc,aAAa,cAAc;MAClD;;;;;;EAeH,WAAW,uBAAqB,aAClB,cAAc,eACzB;;;iBAMY,OAAO,iBAAiB,SAAS"}

package/dist/fake-JXbkdao8.d.mts

@@ -0,0 +1,201 @@
+import { n as StandardSchemaV1 } from "./index-DdRjYhiJ.mjs";
+import { r as Consumable } from "./construct-interface-ZvYQbivO.mjs";
+import { n as DeployedStage, r as LocalStage } from "./stages-BSCF19o2.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$1<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+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;
+}
+declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value$1<TSchema>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Value$1<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.
+ */
+declare function readCredentials<TSchema extends StandardSchemaV1>(id: string, key: string, schema: TSchema, envParser: ServiceRegisterOptions['envParser']): Promise<Value$1<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.
+ */
+declare function decodeCredentials(raw: string): unknown;
+/** A credential was set, and is not what its schema says it should be. */
+declare class MalformedCredential extends Error {
+  readonly id: string;
+  readonly key: string;
+  readonly issues: unknown;
+  constructor(id: string, key: string, issues: unknown);
+}
+//#endregion
+//#region src/external-api.d.ts
+/** What a credentials schema yields. */
+type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+/**
+ * Where an external API answers: one URL for every stage, or one per stage
+ * name with `default` for any stage not listed.
+ *
+ * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,
+ * so a key that names no stage — `prodution` — is a type error rather than a
+ * URL nothing reads. Without the file any key goes, as before.
+ */
+type ExternalApiUrl = string | (string extends LocalStage | DeployedStage ? Readonly<Record<string, string>> : { readonly [S in LocalStage | DeployedStage]?: string; } & {
+  readonly default?: string;
+});
+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: ExternalApiUrl;
+  /** 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>);
+  /**
+   * 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;
+}
+//#endregion
+//#region src/fake.d.ts
+/**
+ * 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;
+/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */
+interface FetchHandler {
+  fetch(request: Request): Response | Promise<Response>;
+}
+/**
+ * What a construct's credentials look like going in, for a fake to supply —
+ * an external API's `credentials` schema, or a credential's `schema`.
+ */
+type CredentialsOf<TConstruct> = TConstruct extends ExternalApi<string, infer TSchema, unknown> ? StandardSchemaV1.InferInput<TSchema> : TConstruct extends Credential<string, infer TSchema> ? StandardSchemaV1.InferInput<TSchema> : unknown;
+/**
+ * A third party's stand-in, as `test/fakes/<id>.ts` default-exports it.
+ *
+ * `credentials` are what a local or test stage is handed as `<ID>_CREDENTIALS`
+ * in place of the stage's own: what an external API's fake accepts, or a
+ * credential's test value.
+ */
+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;
+} | {
+  /** A `Credential`'s test value — nothing to serve. */
+  readonly kind: 'credential';
+});
+/**
+ * Build the fake `test/fakes/<id>.ts` default-exports.
+ *
+ * Pass the construct's type to have the value checked against its schema —
+ * `fake.app<typeof polar>(…)`, `fake.credential<typeof stripe>(…)`.
+ */
+declare const fake: {
+  /** A working implementation of an external API, kept beside the tests that use it. */
+  app<TApi = unknown>(handler: FetchHandler, options: {
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /** A local server an external API's provider publishes — `stripe/stripe-mock`. */
+  image<TApi = unknown>(image: string, options: {
+    port: number;
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /**
+   * A `Credential`'s value on the test stage and under `gkm dev --fake`, as
+   * its schema takes it — a string, or the object a JSON credential holds.
+   * It is validated where it is read, like the real one.
+   */
+  credential<TCredential = unknown>(credentials: CredentialsOf<TCredential>): 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 { ExternalApi as a, Credential as c, decodeCredentials as d, readCredentials as f, isFake as i, CredentialOptions as l, FetchHandler as n, ExternalApiOptions as o, fake as r, ExternalApiUrl as s, Fake as t, MalformedCredential as u };
+//# sourceMappingURL=fake-JXbkdao8.d.mts.map

package/dist/fake-JXbkdao8.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-JXbkdao8.d.mts","names":["Value"],"sources":["../src/credential.ts","../src/external-api.ts","../src/fake.ts"],"mappings":";;;;;;;KAiEKA,QAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;UAEb,kBAAkB,gBAAgB;;;;;;;;EAQlD,QAAQ;;;;;;;;;;EAUR;;cAGY,WACZ,+BACA,gBAAgB,mBAAmB,6BACvB,WAAW,OAAOA,QAAM;mBA6BlB;WApBT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQA,QAAM;;;;;mBAMpC;;;;;;;;UAST;EAER,YACC,IAAI,cAAc,QACD,SAAS,kBAAkB;;;;;;;MAoBzC,qBAAqB;EAIzB,WAAW;UAUH;UAQA;;;;;;;;;;;iBAmBa,gBAAgB,gBAAgB,kBACrD,YACA,aACA,QAAQ,SACR,WAAW,sCACT,QAAQA,QAAM;;;;;;;;;;;iBAsBD,kBAAkB;;cAoBrB,4BAA4B;WAE9B;WACA;WACA;EAHV,YACU,YACA,aACA;;;;;KCpLN,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;;;;;;;;;KAUlB,0CAEO,aAAa,gBAC3B,SAAS,sCACG,KAAK,aAAa;WACrB;;UAGG,mBAAmB,gBAAgB,kBAAkB;;;;;EAKrE,KAAK;;EAEL,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;;;;;;;MA0BnD,qBAAqB;EAIzB,WAAW;UAaG;;;;;;;;cCjHT;;UAGW;EAChB,MAAM,SAAS,UAAU,WAAW,QAAQ;;;;;;KAOxC,cAAc,cAClB,mBAAmB,0BAA0B,oBAC1C,iBAAiB,WAAW,WAC5B,mBAAmB,yBAAyB,WAC3C,iBAAiB,WAAW;;;;;;;;KAUrB;YACD;WACD;;WAGE;;WAEA,SAAS;;WAGT;;WAEA;;WAEA;;;WAIA;;;;;;;;cAUC;;EAEZ,IAAI,gBAAc,SACR,cAAY;IACV,aAAa,cAAc;MACpC;;EAUH,MAAM,gBAAc,eACN;IACF;IAAc,aAAa,cAAc;MAClD;;;;;;EAeH,WAAW,uBAAqB,aAClB,cAAc,eACzB;;;iBAMY,OAAO,iBAAiB,SAAS"}

package/dist/file-server.cjs

@@ -1,10 +1,58 @@
-const require_chunk = require('./chunk-DWy1uDak.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_storage = require_chunk.__toESM(require("@geekmidas/storage"));
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_expire = require("./expire-CieftS01.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _geekmidas_storage = require("@geekmidas/storage");
 //#region src/file-server.ts
+/**
+* `FileServer` — a domain that serves a bucket's objects.
+*
+* `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never
+* public. Serving those objects on a domain is a different thing, and it is a
+* construct of its own rather than a flag on the bucket — see
+* `docs/design/constructs-paradigm.md`, "Why a separate construct, and what it
+* costs", for the comparison that rules the other two shapes out.
+*
+* ```ts
+* export const uploads = new FileServer('Uploads', { open: ['brand/**'] });
+*
+* uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket
+* uploads.url('brand/logo.png')                // open path — no signature
+* uploads.signedUrl('invoices/7.pdf')          // one object, one recipient
+* ```
+*
+* **One construct, one client, both halves.** How a file lands in the bucket is
+* the same whether or not it is served, so splitting the upload half from the
+* serving half would be ceremony rather than safety. The client is a *superset*
+* of `StorageClient`, made literal in the type, so anything taking
+* `services.uploads` keeps compiling when the construct behind it grows a
+* serving half.
+*
+* **The id names the bucket, not the surface.** This is the detail that has to
+* be right before anything ships, because getting it backwards is destructive:
+* the migration people actually perform is serving a bucket they already have,
+* and naming the bucket after the construct makes that edit *add* a node rather
+* than rename the one holding the data.
+*/
+/**
+* A bucket setting given to a file server that fronts a bucket declared
+* elsewhere — where the bucket's own construct is the one that says it.
+*/
+var BucketOptionOnOrigin = class extends Error {
+	server;
+	origin;
+	option;
+	constructor(server, origin, option) {
+		super(`'${server}' fronts '${origin}', which declares itself, so '${option}' belongs on the construct that declares '${origin}', not on the file server.`);
+		this.server = server;
+		this.origin = origin;
+		this.option = option;
+		this.name = "BucketOptionOnOrigin";
+	}
+};
 /** A key was asked to be served unsigned, and no open pattern admits it. */
 var NotOpen = class extends Error {
+	key;
+	open;
 	constructor(key, open) {
 		super(`'${key}' is not served without a signature. ` + (open.length ? `Open paths: ${open.join(", ")}. Use signedUrl() for anything else.` : "This file server declares no open paths, so every object needs signedUrl()."));
 		this.key = key;
@@ -13,11 +61,14 @@ var NotOpen = class extends Error {
 	}
 };
 var FileServer = class {
+	options;
 	id;
 	service;
 	/** The id of the surface node, as opposed to the bucket's. */
 	surfaceId;
 	open;
+	/** The vended bucket's expiry, checked once: prefix → days. */
+	expire;
 	/**
 	* Declared once and read by both `declare()` and `connect()`, so the keys the
 	* target publishes and the keys the client reads cannot drift.
@@ -25,17 +76,19 @@ var FileServer = class {
 	keys;
 	constructor(id, options = {}) {
 		this.options = options;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
 		this.id = canonical;
 		this.open = options.open ?? [];
 		const originId = options.origin?.id ?? canonical;
+		if (options.origin && options.expire) throw new BucketOptionOnOrigin(canonical, originId, "expire");
+		this.expire = require_expire.expiryDays(canonical, options.expire);
 		this.surfaceId = `${canonical}Server`;
 		this.keys = {
-			origin: (0, __geekmidas_manifest.provideKey)(originId, "url"),
-			server: (0, __geekmidas_manifest.provideKey)(this.surfaceId, "url")
+			origin: (0, _geekmidas_manifest.provideKey)(originId, "url"),
+			server: (0, _geekmidas_manifest.provideKey)(this.surfaceId, "url")
 		};
 		this.service = {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
 			register: (registerOptions) => this.connect(registerOptions)
 		};
 	}
@@ -83,7 +136,8 @@ var FileServer = class {
 			kind: "objects",
 			id: this.id,
 			provides: [this.keys.origin],
-			...this.options.versioned ? { versioned: true } : {}
+			...this.options.versioned ? { versioned: true } : {},
+			...this.expire ? { expire: this.expire } : {}
 		}, surface];
 	}
 	/**
@@ -99,7 +153,7 @@ var FileServer = class {
 			origin: get(this.keys.origin).string(),
 			server: get(this.keys.server).string()
 		})).parse();
-		const storage = (0, __geekmidas_storage.createStorageClient)(origin);
+		const storage = (0, _geekmidas_storage.createStorageClient)(origin);
 		const base = server.replace(/\/+$/, "");
 		const serve = (key) => {
 			if (!this.serves(key)) throw new NotOpen(key, this.open);
@@ -147,8 +201,9 @@ function globToRegExp(pattern) {
 	}
 	return new RegExp(`^${source}$`);
 }
-
 //#endregion
+exports.BucketOptionOnOrigin = BucketOptionOnOrigin;
 exports.FileServer = FileServer;
 exports.NotOpen = NotOpen;
+
 //# sourceMappingURL=file-server.cjs.map