@geekmidas/constructs 10.0.0-alpha.4 → 10.0.0-alpha.40

package/dist/credential.cjs

@@ -1,9 +1,40 @@
-const require_chunk = require('./chunk-DWy1uDak.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_schema_parser = require_chunk.__toESM(require("@geekmidas/schema/parser"));
-
+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;
 	/**
@@ -21,11 +52,11 @@ var Credential = class {
 	resolved;
 	constructor(id, options) {
 		this.options = options;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
 		this.id = canonical;
-		this.keys = { credential: (0, __geekmidas_manifest.provideKey)(canonical, "credential") };
+		this.keys = { credentials: (0, _geekmidas_manifest.provideKey)(canonical, "credentials") };
 		this.service = {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
 			register: (registerOptions) => this.connect(registerOptions)
 		};
 	}
@@ -33,7 +64,7 @@ var Credential = class {
 		return [{
 			kind: "credential",
 			id: this.id,
-			provides: [this.keys.credential]
+			provides: [this.keys.credentials]
 		}];
 	}
 	connect(options) {
@@ -41,16 +72,28 @@ var Credential = class {
 		this.resolved ??= this.resolve(options);
 		return this.resolved;
 	}
-	async resolve(options) {
-		const { raw } = options.envParser.create((get) => ({ raw: get(this.keys.credential).string() })).parse();
-		try {
-			return await (0, __geekmidas_schema_parser.parseSchema)(this.options.schema, decode(raw));
-		} catch (issues) {
-			throw new MalformedCredential(this.id, this.keys.credential, issues);
-		}
+	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, decode(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
@@ -73,6 +116,9 @@ function decode(raw) {
 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;
@@ -89,8 +135,9 @@ function describe(issues) {
 		return path ? `${path}: ${issue.message}` : issue.message;
 	}).join("; ");
 }
-
 //#endregion
 exports.Credential = Credential;
 exports.MalformedCredential = MalformedCredential;
+exports.readCredentials = readCredentials;
+
 //# sourceMappingURL=credential.cjs.map

package/dist/credential.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"credential.cjs","names":["id: ConstructName<TName>","options: CredentialOptions<TSchema>","options: ServiceRegisterOptions","raw: string","id: string","key: string","issues: unknown","issue: StandardSchemaV1.Issue"],"sources":["../src/credential.ts"],"sourcesContent":["/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { credential: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credential: provideKey(canonical, 'credential') };\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) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credential],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate async resolve(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<Value<TSchema>> {\n\t\tconst { raw } = options.envParser\n\t\t\t.create((get) => ({ raw: get(this.keys.credential).string() }))\n\t\t\t.parse();\n\n\t\ttry {\n\t\t\treturn await parseSchema(this.options.schema, decode(raw));\n\t\t} catch (issues) {\n\t\t\tthrow new MalformedCredential(this.id, this.keys.credential, issues);\n\t\t}\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n */\nfunction decode(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n"],"mappings":";;;;;AAqEA,IAAa,aAAb,MAIA;CAQC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;;;;;;;;CASjB,AAAQ;CAER,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,sCAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO,EAAE,YAAY,qCAAW,WAAW,aAAa,CAAE;AAG/D,OAAK,UAAU;GACd,aAAa,qCAAW,UAAU;GAClC,UAAU,CAAC,oBAAoB,KAAK,QAAQ,gBAAgB;EAC5D;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,UAAW;EAChC,CACD;CACD;CAED,AAAQ,QAAQC,SAA0D;AACzE,MAAI,KAAK,QAAQ,QAAS,QAAO,KAAK,QAAQ,QAAQ;AAEtD,OAAK,aAAa,KAAK,QAAQ,QAAQ;AAEvC,SAAO,KAAK;CACZ;CAED,MAAc,QACbA,SAC0B;EAC1B,MAAM,EAAE,KAAK,GAAG,QAAQ,UACtB,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,KAAK,KAAK,WAAW,CAAC,QAAQ,CAAE,GAAE,CAC9D,OAAO;AAET,MAAI;AACH,UAAO,MAAM,2CAAY,KAAK,QAAQ,QAAQ,OAAO,IAAI,CAAC;EAC1D,SAAQ,QAAQ;AAChB,SAAM,IAAI,oBAAoB,KAAK,IAAI,KAAK,KAAK,YAAY;EAC7D;CACD;AACD;;;;;;;;AASD,SAAS,OAAOC,KAAsB;CACrC,MAAM,QAAQ,IAAI,WAAW,YAAY,GACtC,IAAI,MAAM,YAAY,OAAO,GAC7B;AAEH,KAAI;AACH,SAAO,KAAK,MAAM,MAAM;CACxB,QAAO;AACP,SAAO;CACP;AACD;;;;;;AAOD,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAC9C,YACUC,IACAC,KACAC,QACR;AACD,SACE,EAAE,IAAI,kBAAkB,GAAG,qHAEW,SAAS,OAAO,CAAC,EACxD;EARQ;EACA;EACA;AAOT,OAAK,OAAO;CACZ;AACD;;AAGD,SAAS,SAASA,QAAyB;AAC1C,MAAK,MAAM,QAAQ,OAAO,CAAE,QAAO,OAAO,OAAO;AAEjD,QAAO,OACL,IAAI,CAACC,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,IAAI,CAAC,mBACC,YAAY,WAAW,OAAO,QAAQ,IAAI,GAAG,OAAO,QAAQ,CACnE,CACA,KAAK,IAAI;AAEX,SAAO,QAAQ,EAAE,KAAK,IAAI,MAAM,QAAQ,IAAI,MAAM;CAClD,EAAC,CACD,KAAK,KAAK;AACZ"}
+{"version":3,"file":"credential.cjs","names":["canonicalId","provideKey","serviceKey","parseSchema"],"sources":["../src/credential.ts"],"sourcesContent":["/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { credentials: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credentials: provideKey(canonical, 'credentials') };\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) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate resolve(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\treturn readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.schema,\n\t\t\toptions.envParser,\n\t\t);\n\t}\n}\n\n/**\n * A credentials key, read and validated against its schema.\n *\n * Shared with every construct that holds a third party's credentials — an\n * `ExternalApi` reads its own the same way — so the shape a stage stores and\n * the error a bad value raises are the same everywhere.\n *\n * @throws {MalformedCredential} when the value is not what the schema says.\n */\nexport async function readCredentials<TSchema extends StandardSchemaV1>(\n\tid: string,\n\tkey: string,\n\tschema: TSchema,\n\tenvParser: ServiceRegisterOptions['envParser'],\n): Promise<Value<TSchema>> {\n\tconst { raw } = envParser\n\t\t.create((get) => ({ raw: get(key).string() }))\n\t\t.parse();\n\n\ttry {\n\t\treturn await parseSchema(schema, decode(raw));\n\t} catch (issues) {\n\t\tthrow new MalformedCredential(id, key, issues);\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n */\nfunction decode(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,IAAa,aAAb,MAIA;CA4BmB;CApBlB;CACA;;;;;CAMA;;;;;;;;CASA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,aAAA,GAAYA,oBAAAA,YAAAA,CAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO,EAAE,cAAA,GAAaC,oBAAAA,WAAAA,CAAW,WAAW,aAAa,EAAE;EAGhE,KAAK,UAAU;GACd,cAAA,GAAaC,oBAAAA,WAAAA,CAAW,SAAS;GACjC,WAAW,oBAAoB,KAAK,QAAQ,eAAe;EAC5D;CACD;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,WAAW;EACjC,CACD;CACD;CAEA,QAAgB,SAA0D;EACzE,IAAI,KAAK,QAAQ,SAAS,OAAO,KAAK,QAAQ,OAAO;EAErD,KAAK,aAAa,KAAK,QAAQ,OAAO;EAEtC,OAAO,KAAK;CACb;CAEA,QAAgB,SAA0D;EACzE,OAAO,gBACN,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,QACb,QAAQ,SACT;CACD;AACD;;;;;;;;;;AAWA,eAAsB,gBACrB,IACA,KACA,QACA,WAC0B;CAC1B,MAAM,EAAE,QAAQ,UACd,QAAQ,SAAS,EAAE,KAAK,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAC7C,MAAM;CAER,IAAI;EACH,OAAO,OAAA,GAAMC,yBAAAA,YAAAA,CAAY,QAAQ,OAAO,GAAG,CAAC;CAC7C,SAAS,QAAQ;EAChB,MAAM,IAAI,oBAAoB,IAAI,KAAK,MAAM;CAC9C;AACD;;;;;;;;AASA,SAAS,OAAO,KAAsB;CACrC,MAAM,QAAQ,IAAI,WAAW,WAAW,IACrC,IAAI,MAAM,YAAY,MAAM,IAC5B;CAEH,IAAI;EACH,OAAO,KAAK,MAAM,KAAK;CACxB,QAAQ;EACP,OAAO;CACR;AACD;;;;;;AAOA,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CACA;CAHV,YACC,IACA,KACA,QACC;EACD,MACC,GAAG,IAAI,kBAAkB,GAAG,qHAEW,SAAS,MAAM,GACvD;EARS,KAAA,KAAA;EACA,KAAA,MAAA;EACA,KAAA,SAAA;EAOT,KAAK,OAAO;CACb;AACD;;AAGA,SAAS,SAAS,QAAyB;CAC1C,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,OAAO,OAAO,MAAM;CAEhD,OAAO,OACL,KAAK,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,KAAK,YACN,OAAO,YAAY,WAAW,OAAO,QAAQ,GAAG,IAAI,OAAO,OAAO,CACnE,CAAC,CACA,KAAK,GAAG;EAEV,OAAO,OAAO,GAAG,KAAK,IAAI,MAAM,YAAY,MAAM;CACnD,CAAC,CAAC,CACD,KAAK,IAAI;AACZ"}

package/dist/credential.d.cts

@@ -1,13 +1,11 @@
-import { Consumable } from "./construct-interface-D9d4Gm4p.cjs";
-import { Service } from "@geekmidas/services";
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import { t as StandardSchemaV1 } from "./index-CeEtxDmK.cjs";
+import { r as Consumable } from "./construct-interface-_xi4BPN8.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>;
-interface CredentialOptions<TSchema extends StandardSchemaV1> {
+export interface CredentialOptions<TSchema extends StandardSchemaV1> {
   /**
    * What the credential must look like.
    *
@@ -27,7 +25,7 @@ interface CredentialOptions<TSchema extends StandardSchemaV1> {
    */
   refresh?: boolean;
 }
-declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value<TSchema>> {
+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>>;
@@ -49,13 +47,22 @@ declare class Credential<TName extends string = string, TSchema extends Standard
   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>>;
 /** A credential was set, and is not what its schema says it should be. */
-declare class MalformedCredential extends Error {
+export declare class MalformedCredential extends Error {
   readonly id: string;
   readonly key: string;
   readonly issues: unknown;
   constructor(id: string, key: string, issues: unknown);
 }
 //#endregion
-export { Credential, CredentialOptions, MalformedCredential };
 //# sourceMappingURL=credential.d.cts.map

package/dist/credential.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"credential.d.cts","names":[],"sources":["../src/credential.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAwEuB,KA3BlB,KA2BkB,CAAA,gBA3BI,gBA2BJ,CAAA,GA1BtB,gBAAA,CAAiB,WA0BK,CA1BO,OA0BP,CAAA;AAuGV,UA/HI,iBA+HgB,CAAA,gBA/HkB,gBA+HL,CAAA,CAAA;;;;;;;;UAvHrC;;;;;;;;;;;;cAaI,0DAEI,mBAAmB,6BACvB,WAAW,OAAO,MAAM;;eASvB;oBACK,QAAQ,aAAa,QAAQ,MAAM;;;;;;;;;;;;;;kBAkBhD,cAAc,iBACQ,kBAAkB;aAclC;;;;;cA4DC,mBAAA,SAA4B,KAAK"}
+{"version":3,"file":"credential.d.cts","names":[],"sources":["../src/credential.ts"],"mappings":";;;;;;KA6CK,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;iBAEb,kBAAkB,gBAAgB;;;;;;;;EAQlD,QAAQ;;;;;;;;;;EAUR;;qBAGY,WACZ,+BACA,gBAAgB,mBAAmB,6BACvB,WAAW,OAAO,MAAM;mBA6BlB;WApBT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,MAAM;;;;;mBAMpC;;;;;;;;UAST;EAER,YACC,IAAI,cAAc,QACD,SAAS,kBAAkB;EAc7C,WAAW;UAUH;UAQA;;;;;;;;;;;wBAmBa,gBAAgB,gBAAgB,kBACrD,YACA,aACA,QAAQ,SACR,WAAW,sCACT,QAAQ,MAAM;;qBAuCJ,4BAA4B;WAE9B;WACA;WACA;EAHV,YACU,YACA,aACA"}

package/dist/credential.d.mts

@@ -1,13 +1,11 @@
-import { Consumable } from "./construct-interface-g5GM5pwR.mjs";
+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";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-
+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>;
-interface CredentialOptions<TSchema extends StandardSchemaV1> {
+export interface CredentialOptions<TSchema extends StandardSchemaV1> {
   /**
    * What the credential must look like.
    *
@@ -27,7 +25,7 @@ interface CredentialOptions<TSchema extends StandardSchemaV1> {
    */
   refresh?: boolean;
 }
-declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value<TSchema>> {
+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>>;
@@ -49,13 +47,22 @@ declare class Credential<TName extends string = string, TSchema extends Standard
   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>>;
 /** A credential was set, and is not what its schema says it should be. */
-declare class MalformedCredential extends Error {
+export declare class MalformedCredential extends Error {
   readonly id: string;
   readonly key: string;
   readonly issues: unknown;
   constructor(id: string, key: string, issues: unknown);
 }
 //#endregion
-export { Credential, CredentialOptions, MalformedCredential };
 //# sourceMappingURL=credential.d.mts.map

package/dist/credential.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"credential.d.mts","names":[],"sources":["../src/credential.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAwEuB,KA3BlB,KA2BkB,CAAA,gBA3BI,gBA2BJ,CAAA,GA1BtB,gBAAA,CAAiB,WA0BK,CA1BO,OA0BP,CAAA;AAuGV,UA/HI,iBA+HgB,CAAA,gBA/HkB,gBA+HL,CAAA,CAAA;;;;;;;;UAvHrC;;;;;;;;;;;;cAaI,0DAEI,mBAAmB,6BACvB,WAAW,OAAO,MAAM;;eASvB;oBACK,QAAQ,aAAa,QAAQ,MAAM;;;;;;;;;;;;;;kBAkBhD,cAAc,iBACQ,kBAAkB;aAclC;;;;;cA4DC,mBAAA,SAA4B,KAAK"}
+{"version":3,"file":"credential.d.mts","names":[],"sources":["../src/credential.ts"],"mappings":";;;;;;KA6CK,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;iBAEb,kBAAkB,gBAAgB;;;;;;;;EAQlD,QAAQ;;;;;;;;;;EAUR;;qBAGY,WACZ,+BACA,gBAAgB,mBAAmB,6BACvB,WAAW,OAAO,MAAM;mBA6BlB;WApBT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,MAAM;;;;;mBAMpC;;;;;;;;UAST;EAER,YACC,IAAI,cAAc,QACD,SAAS,kBAAkB;EAc7C,WAAW;UAUH;UAQA;;;;;;;;;;;wBAmBa,gBAAgB,gBAAgB,kBACrD,YACA,aACA,QAAQ,SACR,WAAW,sCACT,QAAQ,MAAM;;qBAuCJ,4BAA4B;WAE9B;WACA;WACA;EAHV,YACU,YACA,aACA"}

package/dist/credential.mjs

@@ -1,8 +1,39 @@
 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;
 	/**
@@ -22,7 +53,7 @@ var Credential = class {
 		this.options = options;
 		const canonical = canonicalId(id);
 		this.id = canonical;
-		this.keys = { credential: provideKey(canonical, "credential") };
+		this.keys = { credentials: provideKey(canonical, "credentials") };
 		this.service = {
 			serviceName: serviceKey(canonical),
 			register: (registerOptions) => this.connect(registerOptions)
@@ -32,7 +63,7 @@ var Credential = class {
 		return [{
 			kind: "credential",
 			id: this.id,
-			provides: [this.keys.credential]
+			provides: [this.keys.credentials]
 		}];
 	}
 	connect(options) {
@@ -40,16 +71,28 @@ var Credential = class {
 		this.resolved ??= this.resolve(options);
 		return this.resolved;
 	}
-	async resolve(options) {
-		const { raw } = options.envParser.create((get) => ({ raw: get(this.keys.credential).string() })).parse();
-		try {
-			return await parseSchema(this.options.schema, decode(raw));
-		} catch (issues) {
-			throw new MalformedCredential(this.id, this.keys.credential, issues);
-		}
+	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, decode(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
@@ -72,6 +115,9 @@ function decode(raw) {
 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;
@@ -88,7 +134,7 @@ function describe(issues) {
 		return path ? `${path}: ${issue.message}` : issue.message;
 	}).join("; ");
 }
-
 //#endregion
-export { Credential, MalformedCredential };
+export { Credential, MalformedCredential, readCredentials };
+
 //# sourceMappingURL=credential.mjs.map

package/dist/credential.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"credential.mjs","names":["id: ConstructName<TName>","options: CredentialOptions<TSchema>","options: ServiceRegisterOptions","raw: string","id: string","key: string","issues: unknown","issue: StandardSchemaV1.Issue"],"sources":["../src/credential.ts"],"sourcesContent":["/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { credential: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credential: provideKey(canonical, 'credential') };\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) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credential],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate async resolve(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<Value<TSchema>> {\n\t\tconst { raw } = options.envParser\n\t\t\t.create((get) => ({ raw: get(this.keys.credential).string() }))\n\t\t\t.parse();\n\n\t\ttry {\n\t\t\treturn await parseSchema(this.options.schema, decode(raw));\n\t\t} catch (issues) {\n\t\t\tthrow new MalformedCredential(this.id, this.keys.credential, issues);\n\t\t}\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n */\nfunction decode(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n"],"mappings":";;;;AAqEA,IAAa,aAAb,MAIA;CAQC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;;;;;;;;CASjB,AAAQ;CAER,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,YAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO,EAAE,YAAY,WAAW,WAAW,aAAa,CAAE;AAG/D,OAAK,UAAU;GACd,aAAa,WAAW,UAAU;GAClC,UAAU,CAAC,oBAAoB,KAAK,QAAQ,gBAAgB;EAC5D;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,UAAW;EAChC,CACD;CACD;CAED,AAAQ,QAAQC,SAA0D;AACzE,MAAI,KAAK,QAAQ,QAAS,QAAO,KAAK,QAAQ,QAAQ;AAEtD,OAAK,aAAa,KAAK,QAAQ,QAAQ;AAEvC,SAAO,KAAK;CACZ;CAED,MAAc,QACbA,SAC0B;EAC1B,MAAM,EAAE,KAAK,GAAG,QAAQ,UACtB,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,KAAK,KAAK,WAAW,CAAC,QAAQ,CAAE,GAAE,CAC9D,OAAO;AAET,MAAI;AACH,UAAO,MAAM,YAAY,KAAK,QAAQ,QAAQ,OAAO,IAAI,CAAC;EAC1D,SAAQ,QAAQ;AAChB,SAAM,IAAI,oBAAoB,KAAK,IAAI,KAAK,KAAK,YAAY;EAC7D;CACD;AACD;;;;;;;;AASD,SAAS,OAAOC,KAAsB;CACrC,MAAM,QAAQ,IAAI,WAAW,YAAY,GACtC,IAAI,MAAM,YAAY,OAAO,GAC7B;AAEH,KAAI;AACH,SAAO,KAAK,MAAM,MAAM;CACxB,QAAO;AACP,SAAO;CACP;AACD;;;;;;AAOD,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAC9C,YACUC,IACAC,KACAC,QACR;AACD,SACE,EAAE,IAAI,kBAAkB,GAAG,qHAEW,SAAS,OAAO,CAAC,EACxD;EARQ;EACA;EACA;AAOT,OAAK,OAAO;CACZ;AACD;;AAGD,SAAS,SAASA,QAAyB;AAC1C,MAAK,MAAM,QAAQ,OAAO,CAAE,QAAO,OAAO,OAAO;AAEjD,QAAO,OACL,IAAI,CAACC,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,IAAI,CAAC,mBACC,YAAY,WAAW,OAAO,QAAQ,IAAI,GAAG,OAAO,QAAQ,CACnE,CACA,KAAK,IAAI;AAEX,SAAO,QAAQ,EAAE,KAAK,IAAI,MAAM,QAAQ,IAAI,MAAM;CAClD,EAAC,CACD,KAAK,KAAK;AACZ"}
+{"version":3,"file":"credential.mjs","names":[],"sources":["../src/credential.ts"],"sourcesContent":["/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { credentials: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credentials: provideKey(canonical, 'credentials') };\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) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate resolve(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\treturn readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.schema,\n\t\t\toptions.envParser,\n\t\t);\n\t}\n}\n\n/**\n * A credentials key, read and validated against its schema.\n *\n * Shared with every construct that holds a third party's credentials — an\n * `ExternalApi` reads its own the same way — so the shape a stage stores and\n * the error a bad value raises are the same everywhere.\n *\n * @throws {MalformedCredential} when the value is not what the schema says.\n */\nexport async function readCredentials<TSchema extends StandardSchemaV1>(\n\tid: string,\n\tkey: string,\n\tschema: TSchema,\n\tenvParser: ServiceRegisterOptions['envParser'],\n): Promise<Value<TSchema>> {\n\tconst { raw } = envParser\n\t\t.create((get) => ({ raw: get(key).string() }))\n\t\t.parse();\n\n\ttry {\n\t\treturn await parseSchema(schema, decode(raw));\n\t} catch (issues) {\n\t\tthrow new MalformedCredential(id, key, issues);\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n */\nfunction decode(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,IAAa,aAAb,MAIA;CA4BmB;CApBlB;CACA;;;;;CAMA;;;;;;;;CASA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO,EAAE,aAAa,WAAW,WAAW,aAAa,EAAE;EAGhE,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,oBAAoB,KAAK,QAAQ,eAAe;EAC5D;CACD;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,WAAW;EACjC,CACD;CACD;CAEA,QAAgB,SAA0D;EACzE,IAAI,KAAK,QAAQ,SAAS,OAAO,KAAK,QAAQ,OAAO;EAErD,KAAK,aAAa,KAAK,QAAQ,OAAO;EAEtC,OAAO,KAAK;CACb;CAEA,QAAgB,SAA0D;EACzE,OAAO,gBACN,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,QACb,QAAQ,SACT;CACD;AACD;;;;;;;;;;AAWA,eAAsB,gBACrB,IACA,KACA,QACA,WAC0B;CAC1B,MAAM,EAAE,QAAQ,UACd,QAAQ,SAAS,EAAE,KAAK,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAC7C,MAAM;CAER,IAAI;EACH,OAAO,MAAM,YAAY,QAAQ,OAAO,GAAG,CAAC;CAC7C,SAAS,QAAQ;EAChB,MAAM,IAAI,oBAAoB,IAAI,KAAK,MAAM;CAC9C;AACD;;;;;;;;AASA,SAAS,OAAO,KAAsB;CACrC,MAAM,QAAQ,IAAI,WAAW,WAAW,IACrC,IAAI,MAAM,YAAY,MAAM,IAC5B;CAEH,IAAI;EACH,OAAO,KAAK,MAAM,KAAK;CACxB,QAAQ;EACP,OAAO;CACR;AACD;;;;;;AAOA,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CACA;CAHV,YACC,IACA,KACA,QACC;EACD,MACC,GAAG,IAAI,kBAAkB,GAAG,qHAEW,SAAS,MAAM,GACvD;EARS,KAAA,KAAA;EACA,KAAA,MAAA;EACA,KAAA,SAAA;EAOT,KAAK,OAAO;CACb;AACD;;AAGA,SAAS,SAAS,QAAyB;CAC1C,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,OAAO,OAAO,MAAM;CAEhD,OAAO,OACL,KAAK,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,KAAK,YACN,OAAO,YAAY,WAAW,OAAO,QAAQ,GAAG,IAAI,OAAO,OAAO,CACnE,CAAC,CACA,KAAK,GAAG;EAEV,OAAO,OAAO,GAAG,KAAK,IAAI,MAAM,YAAY,MAAM;CACnD,CAAC,CAAC,CACD,KAAK,IAAI;AACZ"}

package/dist/crons/index.cjs

@@ -1,14 +1,72 @@
-require('../construct-interface-BfjcOD_E.cjs');
-require('../Construct-CyS3RpTL.cjs');
-require('../functions-DJJA7VGc.cjs');
-require('../clone-Dy0cR2SZ.cjs');
-const require_CronBuilder = require('../CronBuilder-DyUr6nYz.cjs');
-
-//#region src/crons/index.ts
-const c = new require_CronBuilder.CronBuilder();
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_CronBuilder = require("../CronBuilder-DB35T5dL.cjs");
+//#region src/crons/schedule.ts
+/**
+* A schedule a cron runner can take, as standard five-field cron.
+*
+* `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already
+* five-field cron and unwraps; `rate(n unit)` is an interval, and an interval
+* is not a schedule — it says how often, where cron says when.
+*
+* Most intervals still have an exact cron equivalent, because they divide their
+* unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that
+* is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field
+* that means "every seven hours" — `*​/7` in the hour field fires at 0, 7, 14
+* and 21 and then starts over at midnight, so the gap between the last firing
+* of one day and the first of the next is three hours rather than seven.
+*
+* Those are refused rather than rounded. A job that runs at the wrong hour is
+* far harder to notice than one that refused to build, and a schedule quietly
+* adjusted by the framework is a bug nobody goes looking for.
+*/
+var UnrepresentableSchedule = class extends Error {
+	schedule;
+	constructor(schedule, reason) {
+		super(`\`${schedule}\` has no exact cron equivalent: ${reason}.\n\nCron says *when*, not *how often*, so an interval is only exact when it divides its unit evenly.
+Write the schedule you mean instead — \`cron(0 */6 * * *)\` for every sixth hour, say — or pick an interval that divides: minutes into 60, hours into 24.`);
+		this.schedule = schedule;
+		this.name = "UnrepresentableSchedule";
+	}
+};
+/** Units `rate(…)` accepts, singular or plural. */
+const UNITS = [
+	"minute",
+	"hour",
+	"day"
+];
+/**
+* Standard five-field cron for a schedule expression.
+*
+* @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.
+*/
+function toCronExpression(schedule) {
+	const cron = /^cron\((.+)\)$/.exec(schedule);
+	if (cron?.[1]) return cron[1].trim();
+	const rate = /^rate\(\s*(\d+)\s+(\w+?)s?\s*\)$/.exec(schedule);
+	if (!rate) throw new UnrepresentableSchedule(schedule, "it is neither `cron(…)` nor `rate(n unit)`");
+	const every = Number(rate[1]);
+	const unit = rate[2];
+	/* c8 ignore next */ if (!unit) throw new UnrepresentableSchedule(schedule, "no unit");
+	if (!UNITS.includes(unit)) throw new UnrepresentableSchedule(schedule, `\`${unit}\` is not one of ${UNITS.join(", ")}`);
+	if (every < 1) throw new UnrepresentableSchedule(schedule, "an interval must be at least 1");
+	switch (unit) {
+		case "minute":
+			if (every === 1) return "* * * * *";
+			if (60 % every !== 0) throw new UnrepresentableSchedule(schedule, `${every} does not divide 60, so the interval would reset at the top of each hour`);
+			return `*/${every} * * * *`;
+		case "hour":
+			if (every === 1) return "0 * * * *";
+			if (24 % every !== 0) throw new UnrepresentableSchedule(schedule, `${every} does not divide 24, so the interval would reset at midnight`);
+			return `0 */${every} * * *`;
+		case "day":
+			if (every === 1) return "0 0 * * *";
+			throw new UnrepresentableSchedule(schedule, "day-of-month restarts every month, so no multi-day interval is even");
+	}
+}
 //#endregion
 exports.Cron = require_CronBuilder.Cron;
 exports.CronBuilder = require_CronBuilder.CronBuilder;
-exports.c = c;
+exports.UnrepresentableSchedule = UnrepresentableSchedule;
+exports.toCronExpression = toCronExpression;
+
 //# sourceMappingURL=index.cjs.map

package/dist/crons/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["CronBuilder"],"sources":["../../src/crons/index.ts"],"sourcesContent":["export {\n\tCron,\n\ttype CronExpression,\n\ttype RateExpression,\n\ttype ScheduleExpression,\n} from './Cron';\nexport { CronBuilder } from './CronBuilder';\n\nimport { CronBuilder } from './CronBuilder';\n\nexport const c = new CronBuilder();\n"],"mappings":";;;;;;;AAUA,MAAa,IAAI,IAAIA"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/crons/schedule.ts"],"sourcesContent":["import type { ScheduleExpression } from './Cron';\n\n/**\n * A schedule a cron runner can take, as standard five-field cron.\n *\n * `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already\n * five-field cron and unwraps; `rate(n unit)` is an interval, and an interval\n * is not a schedule — it says how often, where cron says when.\n *\n * Most intervals still have an exact cron equivalent, because they divide their\n * unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that\n * is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field\n * that means \"every seven hours\" — `*​/7` in the hour field fires at 0, 7, 14\n * and 21 and then starts over at midnight, so the gap between the last firing\n * of one day and the first of the next is three hours rather than seven.\n *\n * Those are refused rather than rounded. A job that runs at the wrong hour is\n * far harder to notice than one that refused to build, and a schedule quietly\n * adjusted by the framework is a bug nobody goes looking for.\n */\nexport class UnrepresentableSchedule extends Error {\n\tconstructor(\n\t\treadonly schedule: string,\n\t\treason: string,\n\t) {\n\t\tsuper(\n\t\t\t`\\`${schedule}\\` has no exact cron equivalent: ${reason}.\\n\\n` +\n\t\t\t\t'Cron says *when*, not *how often*, so an interval is only exact when ' +\n\t\t\t\t'it divides its unit evenly.\\n' +\n\t\t\t\t'Write the schedule you mean instead — `cron(0 */6 * * *)` for every ' +\n\t\t\t\t'sixth hour, say — or pick an interval that divides: minutes into 60, ' +\n\t\t\t\t'hours into 24.',\n\t\t);\n\t\tthis.name = 'UnrepresentableSchedule';\n\t}\n}\n\n/** Units `rate(…)` accepts, singular or plural. */\nconst UNITS = ['minute', 'hour', 'day'] as const;\ntype Unit = (typeof UNITS)[number];\n\n/**\n * Standard five-field cron for a schedule expression.\n *\n * @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.\n */\nexport function toCronExpression(schedule: ScheduleExpression): string {\n\tconst cron = /^cron\\((.+)\\)$/.exec(schedule);\n\tif (cron?.[1]) return cron[1].trim();\n\n\tconst rate = /^rate\\(\\s*(\\d+)\\s+(\\w+?)s?\\s*\\)$/.exec(schedule);\n\tif (!rate) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t'it is neither `cron(…)` nor `rate(n unit)`',\n\t\t);\n\t}\n\n\tconst every = Number(rate[1]);\n\tconst unit = rate[2] as Unit;\n\t/* c8 ignore next */ if (!unit)\n\t\tthrow new UnrepresentableSchedule(schedule, 'no unit');\n\n\tif (!UNITS.includes(unit)) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t`\\`${unit}\\` is not one of ${UNITS.join(', ')}`,\n\t\t);\n\t}\n\n\tif (every < 1) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t'an interval must be at least 1',\n\t\t);\n\t}\n\n\tswitch (unit) {\n\t\tcase 'minute':\n\t\t\tif (every === 1) return '* * * * *';\n\t\t\tif (60 % every !== 0) {\n\t\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\t\tschedule,\n\t\t\t\t\t`${every} does not divide 60, so the interval would reset at the top of each hour`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn `*/${every} * * * *`;\n\n\t\tcase 'hour':\n\t\t\tif (every === 1) return '0 * * * *';\n\t\t\tif (24 % every !== 0) {\n\t\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\t\tschedule,\n\t\t\t\t\t`${every} does not divide 24, so the interval would reset at midnight`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn `0 */${every} * * *`;\n\n\t\tcase 'day':\n\t\t\tif (every === 1) return '0 0 * * *';\n\t\t\t// `*/n` in day-of-month restarts on the 1st, so a 2-day interval fires\n\t\t\t// on the 1st and 3rd of a 31-day month and then again on the 1st — one\n\t\t\t// day later, not two. No month length makes that come out even.\n\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\tschedule,\n\t\t\t\t'day-of-month restarts every month, so no multi-day interval is even',\n\t\t\t);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoBA,IAAa,0BAAb,cAA6C,MAAM;CAExC;CADV,YACC,UACA,QACC;EACD,MACC,KAAK,SAAS,mCAAmC,OAAO;0JAMzD;EAVS,KAAA,WAAA;EAWT,KAAK,OAAO;CACb;AACD;;AAGA,MAAM,QAAQ;CAAC;CAAU;CAAQ;AAAK;;;;;;AAQtC,SAAgB,iBAAiB,UAAsC;CACtE,MAAM,OAAO,iBAAiB,KAAK,QAAQ;CAC3C,IAAI,OAAO,IAAI,OAAO,KAAK,EAAE,CAAC,KAAK;CAEnC,MAAM,OAAO,mCAAmC,KAAK,QAAQ;CAC7D,IAAI,CAAC,MACJ,MAAM,IAAI,wBACT,UACA,4CACD;CAGD,MAAM,QAAQ,OAAO,KAAK,EAAE;CAC5B,MAAM,OAAO,KAAK;sBACG,IAAI,CAAC,MACzB,MAAM,IAAI,wBAAwB,UAAU,SAAS;CAEtD,IAAI,CAAC,MAAM,SAAS,IAAI,GACvB,MAAM,IAAI,wBACT,UACA,KAAK,KAAK,mBAAmB,MAAM,KAAK,IAAI,GAC7C;CAGD,IAAI,QAAQ,GACX,MAAM,IAAI,wBACT,UACA,gCACD;CAGD,QAAQ,MAAR;EACC,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GACxB,IAAI,KAAK,UAAU,GAClB,MAAM,IAAI,wBACT,UACA,GAAG,MAAM,yEACV;GAED,OAAO,KAAK,MAAM;EAEnB,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GACxB,IAAI,KAAK,UAAU,GAClB,MAAM,IAAI,wBACT,UACA,GAAG,MAAM,6DACV;GAED,OAAO,OAAO,MAAM;EAErB,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GAIxB,MAAM,IAAI,wBACT,UACA,qEACD;CACF;AACD"}

package/dist/crons/index.d.cts

@@ -1,16 +1,34 @@
-import "../Construct-C0ijr2qp.cjs";
-import "../index-AIfVzkhi.cjs";
-import "../construct-interface-D9d4Gm4p.cjs";
-import { Cron, CronExpression, RateExpression, ScheduleExpression } from "../Cron-B2OFsfDM.cjs";
-import { CronBuilder } from "../CronBuilder-LSJMfqnq.cjs";
-import * as _geekmidas_logger2 from "@geekmidas/logger";
-import * as _geekmidas_schema0 from "@geekmidas/schema";
-import * as _geekmidas_services1 from "@geekmidas/services";
-
-//#region src/crons/index.d.ts
-declare const c: CronBuilder<_geekmidas_schema0.ComposableStandardSchema, _geekmidas_services1.Service<string, unknown>[], _geekmidas_logger2.Logger, undefined, undefined, string, undefined, string>;
-//# sourceMappingURL=index.d.ts.map
-
+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.
+ *
+ * `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already
+ * five-field cron and unwraps; `rate(n unit)` is an interval, and an interval
+ * is not a schedule — it says how often, where cron says when.
+ *
+ * Most intervals still have an exact cron equivalent, because they divide their
+ * unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that
+ * is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field
+ * that means "every seven hours" — `*​/7` in the hour field fires at 0, 7, 14
+ * and 21 and then starts over at midnight, so the gap between the last firing
+ * of one day and the first of the next is three hours rather than seven.
+ *
+ * Those are refused rather than rounded. A job that runs at the wrong hour is
+ * far harder to notice than one that refused to build, and a schedule quietly
+ * adjusted by the framework is a bug nobody goes looking for.
+ */
+export declare class UnrepresentableSchedule extends Error {
+  readonly schedule: string;
+  constructor(schedule: string, reason: string);
+}
+/**
+ * Standard five-field cron for a schedule expression.
+ *
+ * @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.
+ */
+export declare function toCronExpression(schedule: ScheduleExpression): string;
 //#endregion
-export { Cron, CronBuilder, CronExpression, RateExpression, ScheduleExpression, c };
+export { Cron, CronBuilder, type CronExpression, type RateExpression, type ScheduleExpression };
 //# sourceMappingURL=index.d.cts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/crons/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAUa,GAAC,YAAoB,kBAAA,CAApB,wBAAA,EAAA,oBAAA,CAAA,4BAAA,kBAAA,CAAA,MAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/crons/schedule.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;qBAoBa,gCAAgC;WAElC;EADV,YACU,kBACT;;;;;;;wBAuBc,iBAAiB,UAAU"}