@geekmidas/constructs 9.0.2 → 10.0.0-alpha.0

package/dist/database/kysely.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.d.cts","names":[],"sources":["../../src/database/kysely.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;AAqGM,UA7DW,qBAAA,SAA8B,IA6DzC,CA7D8C,YA6D9C,EAAA,SAAA,CAAA,CAAA;EAAa;;;;;;;EAyGoB,MACnB,CAAA,EAAA,MAAA;EAAM;;;;;;;EAoBC,KAAE,CAAA,EAAA,OAAA;EAAO;;;;;;;AA9If;AA4OrB;;EAA4B,OACZ,CAAA,EA/PL,eA+PK;;;UA3PN,WAAA,CA0P+C;EAAI,IAAA,EAAA,iBAAA,GAAA,iBAAA;;;;;;;;;;;cA7OhD,uEACD,UAAU,OAAO,OAAO;;eAEtB;oBACK,QAAQ,aAAa,QAAQ,OAAO;;;;;;;;;;kBAajD,cAAc,kBACQ,qCACZ;aAyBJ;;;;;;;;;;;;;YAqDD,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;mCAyBD,mBAC5B,cAAc;;MAEhB,MAAM;;;;;;;;;+CAgBJ,cAAc,oBACT,wBACP,eAAe,UAAU;;;;;;;;;;;;;eAoBf,WAAW,aAAa,eAAe,OAAO;;;;;;;;;;;;;;;;;;;;KA0EhD,6CAA6C,KACxD,eAAe,IAAI"}

package/dist/database/kysely.d.mts

@@ -0,0 +1,152 @@
+import { Construct } from "../construct-interface-BqwRNYA2.mjs";
+import { Cache } from "../cache-DYoJFcfd.mjs";
+import { ConstructName, Declaration, PostgresVersion } from "@geekmidas/manifest";
+import { Service } from "@geekmidas/services";
+import { Kysely, KyselyConfig } from "kysely";
+
+//#region src/database/kysely.d.ts
+
+/**
+ * Everything Kysely takes, plus what this construct declares.
+ *
+ * `dialect` is omitted because the construct owns it — it is built from the one
+ * URL the adapter supplied, which is the whole point of the construct. The rest
+ * of `KyselyConfig` (`plugins`, `log`) is the app's business and passes
+ * straight through, so anything Kysely adds later arrives without being
+ * tracked here.
+ */
+interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
+  /**
+   * The schema, pinned on both roles' `search_path`.
+   *
+   * Defaults to `app` — the role the schema plays, rather than a restatement
+   * of the database's own name, which reads correctly beside `auth` and
+   * `pgboss` and keeps the application off `public`.
+   */
+  schema?: string;
+  /**
+   * Provision the owner/runtime role split. Defaults to on.
+   *
+   * Off falls back to the cluster's master credential in both URLs, giving up
+   * the DDL/DML split and putting credentials that can drop a table into the
+   * function's environment. A deliberate downgrade, not a default.
+   */
+  roles?: boolean;
+  /**
+   * The Postgres major version to provision.
+   *
+   * Declared here so one statement reaches both targets. It was previously
+   * set in two unrelated places — a container tag locally, nothing at all on
+   * AWS (so Aurora chose) — which is how local came to run 18 while deployed
+   * ran 17.7 with nothing recording the difference.
+   *
+   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   */
+  version?: PostgresVersion;
+}
+/** What makes a construct derived rather than a database in its own right. */
+interface DerivedFrom {
+  kind: 'database-reader' | 'database-schema';
+  of: string;
+  schema?: string;
+}
+/**
+ * @typeParam DB - the database's schema.
+ * @typeParam TName - the canonical id. TypeScript has no partial
+ * type-argument inference, so `new KyselyDatabase<OrdersDB>('orders')` leaves
+ * this at its default and the service key widens to `string`. `db` still types
+ * through `.database()`, which infers from the service.
+ */
+declare class KyselyDatabase<DB = unknown, TName extends string = string> implements Construct<TName, Kysely<DB>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Kysely<DB>>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * build publishes and the key the client reads cannot drift.
+   */
+  private readonly config;
+  private readonly schemaName;
+  private readonly roles;
+  private readonly version;
+  private readonly derivedFrom?;
+  constructor(id: ConstructName<TName>, options?: KyselyDatabaseOptions, derivedFrom?: DerivedFrom);
+  declare(): Declaration[];
+  /**
+   * A read-only endpoint on this database.
+   *
+   * Read-only is enforced by the reader role's grants rather than by which
+   * endpoint it resolves to, so falling back to the writer where no replica
+   * exists is safe rather than a silently writable connection behind a name
+   * that says reader. There is no `writer()`: the database *is* the writer, so
+   * a replica can never be reached by accident.
+   *
+   * The return type is narrower than this class on purpose — see
+   * {@link ReadOnlyDatabase}.
+   */
+  reader(): ReadOnlyDatabase<DB, `${TName}Reader`>;
+  /**
+   * A cache that lives in this database.
+   *
+   * The same strengthening `schema()` is over a second database: `new
+   * Cache('Sessions')` says the app caches and leaves where to the deployment,
+   * while this says it caches *here* — which is a fact about the application
+   * and so belongs in its code.
+   *
+   * What it buys beyond being explicit: the table's schema and the role that
+   * reaches it come from this database rather than from a second convention,
+   * and the backend no longer has to guess which database "the database" meant
+   * when an app declares two.
+   *
+   * A cache is not a `KyselyDatabase`, so this returns a `Cache` — the client
+   * is a key/value store, not a query builder, and typing it as the parent
+   * would be a convenience that lies.
+   */
+  cache<TCache extends string = `${TName}Cache`>(id?: ConstructName<TCache>, options?: {
+    table?: string;
+  }): Cache<TCache>;
+  /**
+   * A second schema in this database, with its own role(s) and its own URL —
+   * so this database's role holds no grant on those tables at all.
+   *
+   * Typed separately because a tenant has its own tables: the point is that
+   * `auth.selectFrom('sessions')` type-checks and
+   * `orders.selectFrom('sessions')` does not.
+   */
+  schema<TenantDB, TTenant extends string>(id: ConstructName<TTenant>, options?: KyselyDatabaseOptions): KyselyDatabase<TenantDB, TTenant>;
+  /**
+   * A connection as the *owner* role — the one that may create, alter and drop.
+   *
+   * A `Service` rather than part of the construct, and deliberately so: a
+   * construct is what `.dependsOn()` accepts, and nothing should be able to
+   * depend on this. A migrator asks for it by name; a handler cannot ask at
+   * all, which is the security property the role split exists for.
+   *
+   * Falls back to the runtime URL where no owner URL was published — the
+   * `roles: false` downgrade, where there is only one credential and it is the
+   * cluster master's.
+   */
+  get owner(): Service<`${Uncapitalize<TName>}Owner`, Kysely<DB>>;
+  private connect;
+}
+/**
+ * A database you may read through, and derive nothing from.
+ *
+ * A reader is terminal in the graph, and this is that fact in the type system.
+ * `DERIVES_FROM` gives `cache` and `database-schema` no `database-reader`
+ * parent, and there is no reader of a reader — so `orders.reader().cache(…)`
+ * has always been illegal, but it type-checked and failed later at
+ * `assertDerivations`. That is a long way round to learn that a read-only
+ * endpoint cannot own a table something writes to.
+ *
+ * Omitting the three deriving methods rather than making them throw keeps the
+ * failure where it costs least: the editor, on the line that wrote it.
+ *
+ * The result is deliberately not assignable back to `KyselyDatabase` — a
+ * reader is not one, and anything that genuinely needs the writer should say
+ * so.
+ */
+type ReadOnlyDatabase<DB, TName extends string> = Omit<KyselyDatabase<DB, TName>, 'reader' | 'cache' | 'schema'>;
+//#endregion
+export { KyselyDatabase, KyselyDatabaseOptions, ReadOnlyDatabase };
+//# sourceMappingURL=kysely.d.mts.map

package/dist/database/kysely.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.d.mts","names":[],"sources":["../../src/database/kysely.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;AAqGM,UA7DW,qBAAA,SAA8B,IA6DzC,CA7D8C,YA6D9C,EAAA,SAAA,CAAA,CAAA;EAAa;;;;;;;EAyGoB,MACnB,CAAA,EAAA,MAAA;EAAM;;;;;;;EAoBC,KAAE,CAAA,EAAA,OAAA;EAAO;;;;;;;AA9If;AA4OrB;;EAA4B,OACZ,CAAA,EA/PL,eA+PK;;;UA3PN,WAAA,CA0P+C;EAAI,IAAA,EAAA,iBAAA,GAAA,iBAAA;;;;;;;;;;;cA7OhD,uEACD,UAAU,OAAO,OAAO;;eAEtB;oBACK,QAAQ,aAAa,QAAQ,OAAO;;;;;;;;;;kBAajD,cAAc,kBACQ,qCACZ;aAyBJ;;;;;;;;;;;;;YAqDD,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;mCAyBD,mBAC5B,cAAc;;MAEhB,MAAM;;;;;;;;;+CAgBJ,cAAc,oBACT,wBACP,eAAe,UAAU;;;;;;;;;;;;;eAoBf,WAAW,aAAa,eAAe,OAAO;;;;;;;;;;;;;;;;;;;;KA0EhD,6CAA6C,KACxD,eAAe,IAAI"}

package/dist/database/kysely.mjs

@@ -0,0 +1,180 @@
+import { Cache } from "../cache-0ANvRQnD.mjs";
+import { DEFAULT_POSTGRES_VERSION, canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
+import { Kysely, PostgresDialect } from "kysely";
+import pg from "pg";
+
+//#region src/database/kysely.ts
+/** The schema a database uses when it does not say otherwise. */
+const DEFAULT_SCHEMA = "app";
+/**
+* @typeParam DB - the database's schema.
+* @typeParam TName - the canonical id. TypeScript has no partial
+* type-argument inference, so `new KyselyDatabase<OrdersDB>('orders')` leaves
+* this at its default and the service key widens to `string`. `db` still types
+* through `.database()`, which infers from the service.
+*/
+var KyselyDatabase = class KyselyDatabase {
+	id;
+	service;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the key the
+	* build publishes and the key the client reads cannot drift.
+	*/
+	config;
+	schemaName;
+	roles;
+	version;
+	derivedFrom;
+	constructor(id, options = {}, derivedFrom) {
+		this.options = options;
+		const canonical = canonicalId(id);
+		this.id = canonical;
+		this.config = {
+			url: provideKey(canonical, "url"),
+			ownerUrl: provideKey(canonical, "ownerUrl")
+		};
+		this.schemaName = options.schema ?? DEFAULT_SCHEMA;
+		this.roles = options.roles ?? true;
+		this.version = options.version ?? DEFAULT_POSTGRES_VERSION;
+		this.derivedFrom = derivedFrom;
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (registerOptions) => this.connect(registerOptions)
+		};
+	}
+	declare() {
+		if (this.derivedFrom) {
+			const { kind, of, schema } = this.derivedFrom;
+			return [kind === "database-schema" ? {
+				kind,
+				id: this.id,
+				of,
+				schema: schema ?? this.schemaName,
+				provides: [this.config.url]
+			} : {
+				kind,
+				id: this.id,
+				of,
+				provides: [this.config.url]
+			}];
+		}
+		return [{
+			kind: "database",
+			id: this.id,
+			engine: "postgres",
+			schema: this.schemaName,
+			version: this.version,
+			provides: [this.config.url],
+			...this.roles ? {} : { roles: false }
+		}];
+	}
+	/**
+	* A read-only endpoint on this database.
+	*
+	* Read-only is enforced by the reader role's grants rather than by which
+	* endpoint it resolves to, so falling back to the writer where no replica
+	* exists is safe rather than a silently writable connection behind a name
+	* that says reader. There is no `writer()`: the database *is* the writer, so
+	* a replica can never be reached by accident.
+	*
+	* The return type is narrower than this class on purpose — see
+	* {@link ReadOnlyDatabase}.
+	*/
+	reader() {
+		return new KyselyDatabase(`${this.id}Reader`, this.options, {
+			kind: "database-reader",
+			of: this.id
+		});
+	}
+	/**
+	* A cache that lives in this database.
+	*
+	* The same strengthening `schema()` is over a second database: `new
+	* Cache('Sessions')` says the app caches and leaves where to the deployment,
+	* while this says it caches *here* — which is a fact about the application
+	* and so belongs in its code.
+	*
+	* What it buys beyond being explicit: the table's schema and the role that
+	* reaches it come from this database rather than from a second convention,
+	* and the backend no longer has to guess which database "the database" meant
+	* when an app declares two.
+	*
+	* A cache is not a `KyselyDatabase`, so this returns a `Cache` — the client
+	* is a key/value store, not a query builder, and typing it as the parent
+	* would be a convenience that lies.
+	*/
+	cache(id = `${this.id}Cache`, options = {}) {
+		return new Cache(id, {
+			of: this.id,
+			...options.table ? { table: options.table } : {}
+		});
+	}
+	/**
+	* A second schema in this database, with its own role(s) and its own URL —
+	* so this database's role holds no grant on those tables at all.
+	*
+	* Typed separately because a tenant has its own tables: the point is that
+	* `auth.selectFrom('sessions')` type-checks and
+	* `orders.selectFrom('sessions')` does not.
+	*/
+	schema(id, options = {}) {
+		return new KyselyDatabase(id, options, {
+			kind: "database-schema",
+			of: this.id,
+			schema: options.schema ?? id.toLowerCase()
+		});
+	}
+	/**
+	* A connection as the *owner* role — the one that may create, alter and drop.
+	*
+	* A `Service` rather than part of the construct, and deliberately so: a
+	* construct is what `.dependsOn()` accepts, and nothing should be able to
+	* depend on this. A migrator asks for it by name; a handler cannot ask at
+	* all, which is the security property the role split exists for.
+	*
+	* Falls back to the runtime URL where no owner URL was published — the
+	* `roles: false` downgrade, where there is only one credential and it is the
+	* cluster master's.
+	*/
+	get owner() {
+		return {
+			serviceName: `${serviceKey(this.id)}Owner`,
+			register: (options) => this.connect(options, { owner: true })
+		};
+	}
+	async connect(options, as = {}) {
+		const { url, ownerUrl } = options.envParser.create((get) => ({
+			url: get(this.config.url).string(),
+			ownerUrl: get(this.config.ownerUrl).string().optional()
+		})).parse();
+		const { schema: _schema, roles: _roles,...kysely } = this.options;
+		return new Kysely({
+			...kysely,
+			dialect: new PostgresDialect({ pool: pool(as.owner ? ownerUrl ?? url : url) })
+		});
+	}
+};
+/**
+* A pool for one URL, with its schema actually on the search path.
+*
+* `?search_path=` is not a libpq parameter — a URL carrying it connects
+* happily and then resolves every unqualified name against `public`, which is
+* how a schema tenant silently writes its tables into the database it was
+* separated from. Postgres takes it as a startup option instead, so the URL
+* keeps the readable form the target derives and this turns it into the thing
+* the server understands.
+*/
+function pool(url) {
+	const parsed = new URL(url);
+	const searchPath = parsed.searchParams.get("search_path");
+	if (!searchPath) return new pg.Pool({ connectionString: url });
+	parsed.searchParams.delete("search_path");
+	return new pg.Pool({
+		connectionString: parsed.toString(),
+		options: `-c search_path=${searchPath}`
+	});
+}
+
+//#endregion
+export { KyselyDatabase };
+//# sourceMappingURL=kysely.mjs.map

package/dist/database/kysely.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.mjs","names":["id: ConstructName<TName>","options: KyselyDatabaseOptions","derivedFrom?: DerivedFrom","id: ConstructName<TCache>","options: { table?: string }","id: ConstructName<TTenant>","options: ServiceRegisterOptions","as: { owner?: boolean }","url: string"],"sources":["../../src/database/kysely.ts"],"sourcesContent":["/**\n * `KyselyDatabase` — a declared Postgres database, typed by its schema.\n *\n * It declares a logical database, a schema, and the roles that reach it, and\n * hands back a Kysely client built from the one URL the adapter supplied. It\n * names no cloud: `--target=aws` fills that URL from RDS, local dev from the\n * Postgres container.\n *\n * Transactions and RLS context are the execution wrapper's job — it opens the\n * transaction and puts it in `ctx.db`. This construct does not resolve\n * connections per request.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\tDEFAULT_POSTGRES_VERSION,\n\ttype Declaration,\n\ttype PostgresVersion,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport { Kysely, type KyselyConfig, PostgresDialect } from 'kysely';\nimport pg from 'pg';\nimport { Cache } from '../cache';\nimport type { Construct } from '../construct-interface';\n\n/** The schema a database uses when it does not say otherwise. */\nconst DEFAULT_SCHEMA = 'app';\n\n/**\n * Everything Kysely takes, plus what this construct declares.\n *\n * `dialect` is omitted because the construct owns it — it is built from the one\n * URL the adapter supplied, which is the whole point of the construct. The rest\n * of `KyselyConfig` (`plugins`, `log`) is the app's business and passes\n * straight through, so anything Kysely adds later arrives without being\n * tracked here.\n */\nexport interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {\n\t/**\n\t * The schema, pinned on both roles' `search_path`.\n\t *\n\t * Defaults to `app` — the role the schema plays, rather than a restatement\n\t * of the database's own name, which reads correctly beside `auth` and\n\t * `pgboss` and keeps the application off `public`.\n\t */\n\tschema?: string;\n\t/**\n\t * Provision the owner/runtime role split. Defaults to on.\n\t *\n\t * Off falls back to the cluster's master credential in both URLs, giving up\n\t * the DDL/DML split and putting credentials that can drop a table into the\n\t * function's environment. A deliberate downgrade, not a default.\n\t */\n\troles?: boolean;\n\t/**\n\t * The Postgres major version to provision.\n\t *\n\t * Declared here so one statement reaches both targets. It was previously\n\t * set in two unrelated places — a container tag locally, nothing at all on\n\t * AWS (so Aurora chose) — which is how local came to run 18 while deployed\n\t * ran 17.7 with nothing recording the difference.\n\t *\n\t * Defaults to {@link DEFAULT_POSTGRES_VERSION}.\n\t */\n\tversion?: PostgresVersion;\n}\n\n/** What makes a construct derived rather than a database in its own right. */\ninterface DerivedFrom {\n\tkind: 'database-reader' | 'database-schema';\n\tof: string;\n\tschema?: string;\n}\n\n/**\n * @typeParam DB - the database's schema.\n * @typeParam TName - the canonical id. TypeScript has no partial\n * type-argument inference, so `new KyselyDatabase<OrdersDB>('orders')` leaves\n * this at its default and the service key widens to `string`. `db` still types\n * through `.database()`, which infers from the service.\n */\nexport class KyselyDatabase<DB = unknown, TName extends string = string>\n\timplements Construct<TName, Kysely<DB>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Kysely<DB>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly config: { url: string; ownerUrl: string };\n\tprivate readonly schemaName: string;\n\tprivate readonly roles: boolean;\n\tprivate readonly version: PostgresVersion;\n\tprivate readonly derivedFrom?: DerivedFrom;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: KyselyDatabaseOptions = {},\n\t\tderivedFrom?: DerivedFrom,\n\t) {\n\t\t// Canonicalises, so `orders` and `Orders` are one construct rather than\n\t\t// two that collide. Throws on anything that cannot become a valid id.\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.config = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\townerUrl: provideKey(canonical, 'ownerUrl'),\n\t\t};\n\t\tthis.schemaName = options.schema ?? DEFAULT_SCHEMA;\n\t\tthis.roles = options.roles ?? true;\n\t\tthis.version = options.version ?? DEFAULT_POSTGRES_VERSION;\n\t\tthis.derivedFrom = derivedFrom;\n\n\t\t// A field, not a getter: service discovery caches by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\t// Forwards the whole options object — cherry-picking `envParser` strips\n\t\t\t// `context` and with it the request-scoped logger.\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\tif (this.derivedFrom) {\n\t\t\tconst { kind, of, schema } = this.derivedFrom;\n\n\t\t\treturn [\n\t\t\t\tkind === 'database-schema'\n\t\t\t\t\t? {\n\t\t\t\t\t\t\tkind,\n\t\t\t\t\t\t\tid: this.id,\n\t\t\t\t\t\t\tof,\n\t\t\t\t\t\t\tschema: schema ?? this.schemaName,\n\t\t\t\t\t\t\t// The runtime key alone — see the note below on the parent.\n\t\t\t\t\t\t\tprovides: [this.config.url],\n\t\t\t\t\t\t}\n\t\t\t\t\t: {\n\t\t\t\t\t\t\tkind,\n\t\t\t\t\t\t\tid: this.id,\n\t\t\t\t\t\t\tof,\n\t\t\t\t\t\t\t// A reader has no owner URL of its own — nothing migrates\n\t\t\t\t\t\t\t// through a read-only endpoint — so this is the one key.\n\t\t\t\t\t\t\tprovides: [this.config.url],\n\t\t\t\t\t\t},\n\t\t\t];\n\t\t}\n\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'database',\n\t\t\t\tid: this.id,\n\t\t\t\tengine: 'postgres',\n\t\t\t\tschema: this.schemaName,\n\t\t\t\tversion: this.version,\n\t\t\t\t// One key, the runtime role's. `config` also holds the owner key and\n\t\t\t\t// it is deliberately absent here: a key in `provides` is a key an\n\t\t\t\t// edge can name, and nothing should be able to depend on DDL rights.\n\t\t\t\tprovides: [this.config.url],\n\t\t\t\t...(this.roles ? {} : { roles: false }),\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * A read-only endpoint on this database.\n\t *\n\t * Read-only is enforced by the reader role's grants rather than by which\n\t * endpoint it resolves to, so falling back to the writer where no replica\n\t * exists is safe rather than a silently writable connection behind a name\n\t * that says reader. There is no `writer()`: the database *is* the writer, so\n\t * a replica can never be reached by accident.\n\t *\n\t * The return type is narrower than this class on purpose — see\n\t * {@link ReadOnlyDatabase}.\n\t */\n\treader(): ReadOnlyDatabase<DB, `${TName}Reader`> {\n\t\treturn new KyselyDatabase<DB, `${TName}Reader`>(\n\t\t\t`${this.id}Reader` as ConstructName<`${TName}Reader`>,\n\t\t\tthis.options,\n\t\t\t{ kind: 'database-reader', of: this.id },\n\t\t);\n\t}\n\n\t/**\n\t * A cache that lives in this database.\n\t *\n\t * The same strengthening `schema()` is over a second database: `new\n\t * Cache('Sessions')` says the app caches and leaves where to the deployment,\n\t * while this says it caches *here* — which is a fact about the application\n\t * and so belongs in its code.\n\t *\n\t * What it buys beyond being explicit: the table's schema and the role that\n\t * reaches it come from this database rather than from a second convention,\n\t * and the backend no longer has to guess which database \"the database\" meant\n\t * when an app declares two.\n\t *\n\t * A cache is not a `KyselyDatabase`, so this returns a `Cache` — the client\n\t * is a key/value store, not a query builder, and typing it as the parent\n\t * would be a convenience that lies.\n\t */\n\tcache<TCache extends string = `${TName}Cache`>(\n\t\tid: ConstructName<TCache> = `${this.id}Cache` as ConstructName<TCache>,\n\t\toptions: { table?: string } = {},\n\t): Cache<TCache> {\n\t\treturn new Cache<TCache>(id, {\n\t\t\tof: this.id,\n\t\t\t...(options.table ? { table: options.table } : {}),\n\t\t});\n\t}\n\n\t/**\n\t * A second schema in this database, with its own role(s) and its own URL —\n\t * so this database's role holds no grant on those tables at all.\n\t *\n\t * Typed separately because a tenant has its own tables: the point is that\n\t * `auth.selectFrom('sessions')` type-checks and\n\t * `orders.selectFrom('sessions')` does not.\n\t */\n\tschema<TenantDB, TTenant extends string>(\n\t\tid: ConstructName<TTenant>,\n\t\toptions: KyselyDatabaseOptions = {},\n\t): KyselyDatabase<TenantDB, TTenant> {\n\t\treturn new KyselyDatabase<TenantDB, TTenant>(id, options, {\n\t\t\tkind: 'database-schema',\n\t\t\tof: this.id,\n\t\t\tschema: options.schema ?? (id as string).toLowerCase(),\n\t\t});\n\t}\n\n\t/**\n\t * A connection as the *owner* role — the one that may create, alter and drop.\n\t *\n\t * A `Service` rather than part of the construct, and deliberately so: a\n\t * construct is what `.dependsOn()` accepts, and nothing should be able to\n\t * depend on this. A migrator asks for it by name; a handler cannot ask at\n\t * all, which is the security property the role split exists for.\n\t *\n\t * Falls back to the runtime URL where no owner URL was published — the\n\t * `roles: false` downgrade, where there is only one credential and it is the\n\t * cluster master's.\n\t */\n\tget owner(): Service<`${Uncapitalize<TName>}Owner`, Kysely<DB>> {\n\t\treturn {\n\t\t\tserviceName:\n\t\t\t\t`${serviceKey(this.id)}Owner` as `${Uncapitalize<TName>}Owner`,\n\t\t\tregister: (options) => this.connect(options, { owner: true }),\n\t\t};\n\t}\n\n\tprivate async connect(\n\t\toptions: ServiceRegisterOptions,\n\t\tas: { owner?: boolean } = {},\n\t): Promise<Kysely<DB>> {\n\t\tconst { url, ownerUrl } = options.envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.config.url).string(),\n\t\t\t\townerUrl: get(this.config.ownerUrl).string().optional(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\t// Split what the manifest declared from what Kysely takes, so neither\n\t\t// leaks into the other: `schema` and `roles` describe infrastructure and\n\t\t// mean nothing to a client.\n\t\tconst { schema: _schema, roles: _roles, ...kysely } = this.options;\n\n\t\treturn new Kysely<DB>({\n\t\t\t...kysely,\n\t\t\tdialect: new PostgresDialect({\n\t\t\t\tpool: pool(as.owner ? (ownerUrl ?? url) : url),\n\t\t\t}),\n\t\t});\n\t}\n}\n\n/**\n * A pool for one URL, with its schema actually on the search path.\n *\n * `?search_path=` is not a libpq parameter — a URL carrying it connects\n * happily and then resolves every unqualified name against `public`, which is\n * how a schema tenant silently writes its tables into the database it was\n * separated from. Postgres takes it as a startup option instead, so the URL\n * keeps the readable form the target derives and this turns it into the thing\n * the server understands.\n */\nfunction pool(url: string): pg.Pool {\n\tconst parsed = new URL(url);\n\tconst searchPath = parsed.searchParams.get('search_path');\n\n\tif (!searchPath) return new pg.Pool({ connectionString: url });\n\n\tparsed.searchParams.delete('search_path');\n\n\treturn new pg.Pool({\n\t\tconnectionString: parsed.toString(),\n\t\toptions: `-c search_path=${searchPath}`,\n\t});\n}\n\n/**\n * A database you may read through, and derive nothing from.\n *\n * A reader is terminal in the graph, and this is that fact in the type system.\n * `DERIVES_FROM` gives `cache` and `database-schema` no `database-reader`\n * parent, and there is no reader of a reader — so `orders.reader().cache(…)`\n * has always been illegal, but it type-checked and failed later at\n * `assertDerivations`. That is a long way round to learn that a read-only\n * endpoint cannot own a table something writes to.\n *\n * Omitting the three deriving methods rather than making them throw keeps the\n * failure where it costs least: the editor, on the line that wrote it.\n *\n * The result is deliberately not assignable back to `KyselyDatabase` — a\n * reader is not one, and anything that genuinely needs the writer should say\n * so.\n */\nexport type ReadOnlyDatabase<DB, TName extends string> = Omit<\n\tKyselyDatabase<DB, TName>,\n\t'reader' | 'cache' | 'schema'\n>;\n"],"mappings":"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"}

package/dist/email.cjs

@@ -0,0 +1,59 @@
+const require_chunk = require('./chunk-DWy1uDak.cjs');
+const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
+const __geekmidas_emailkit = require_chunk.__toESM(require("@geekmidas/emailkit"));
+
+//#region src/email.ts
+var Email = class {
+	id;
+	service;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the key the
+	* build publishes and the key the client reads cannot drift.
+	*/
+	keys;
+	constructor(id, options) {
+		this.options = options;
+		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		this.id = canonical;
+		this.keys = {
+			url: (0, __geekmidas_manifest.provideKey)(canonical, "url"),
+			from: (0, __geekmidas_manifest.provideKey)(canonical, "from")
+		};
+		this.service = {
+			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
+			register: (options$1) => this.connect(options$1)
+		};
+	}
+	declare() {
+		return [{
+			kind: "email",
+			id: this.id,
+			provides: [this.keys.url, this.keys.from]
+		}];
+	}
+	/**
+	* Builds the client from the URL the adapter supplied.
+	*
+	* No provider branch and no driver lookup — `parseEmailUrl` turns any of
+	* Mailpit, SES, or Resend into the same transport config, which is the whole
+	* reason the scheme is always `smtp://`.
+	*/
+	async connect({ envParser }) {
+		const { url, from } = envParser.create((get) => ({
+			url: get(this.keys.url).string(),
+			from: get(this.keys.from).string()
+		})).parse();
+		return (0, __geekmidas_emailkit.createEmailClient)({
+			smtp: (0, __geekmidas_emailkit.parseEmailUrl)(url),
+			templates: this.options.templates,
+			defaults: {
+				from,
+				...this.options.replyTo ? { replyTo: this.options.replyTo } : {}
+			}
+		});
+	}
+};
+
+//#endregion
+exports.Email = Email;
+//# sourceMappingURL=email.cjs.map

package/dist/email.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.cjs","names":["id: ConstructName<TName>","options: EmailOptions<TTemplates>","options"],"sources":["../src/email.ts"],"sourcesContent":["/**\n * `Email` — declared outbound mail.\n *\n * The same three-package meeting point as `ObjectStorage`: it implements the\n * construct contract, derives its env key through `@geekmidas/manifest`, and\n * hands back an `@geekmidas/emailkit` client. It names no provider — locally the\n * injected URL points at Mailpit, deployed it points at SES or whichever service\n * config selected.\n *\n * Where object storage needs a driver per provider, this needs none: mail is\n * delivered over SMTP whoever delivers it, so there is one client and one URL\n * shape, and the provider survives only as a host and a credential.\n */\n\nimport {\n\tcreateEmailClient,\n\ttype EmailClient,\n\tparseEmailUrl,\n\ttype TemplateRecord,\n} from '@geekmidas/emailkit';\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 { Construct } from './construct-interface';\n\nexport interface EmailOptions<TTemplates extends TemplateRecord> {\n\t/**\n\t * The React templates this app can send.\n\t *\n\t * Structural — they are code, they ship with the handler, and which ones\n\t * exist cannot differ between stages. They are also what types\n\t * `sendTemplate`, so passing them here is what makes the client's call sites\n\t * checkable.\n\t */\n\ttemplates: TTemplates;\n\t/**\n\t * A reply-to address for every send.\n\t *\n\t * `from` is deliberately absent: it belongs to the verified sending domain,\n\t * which is `myapp.test` locally and the real domain deployed, so it arrives\n\t * as stage config rather than being written here.\n\t */\n\treplyTo?: string;\n}\n\nexport class Email<\n\tTName extends string = string,\n\tTTemplates extends TemplateRecord = TemplateRecord,\n> implements Construct<TName, EmailClient<TTemplates>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { url: string; from: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: EmailOptions<TTemplates>,\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\t// The sending identity travels with the URL rather than being a second\n\t\t\t// construct option, for the same reason the URL does: it is the one\n\t\t\t// thing about mail that differs per stage.\n\t\t\tfrom: provideKey(canonical, 'from'),\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: (options) => this.connect(options),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'email',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.url, this.keys.from],\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds the client from the URL the adapter supplied.\n\t *\n\t * No provider branch and no driver lookup — `parseEmailUrl` turns any of\n\t * Mailpit, SES, or Resend into the same transport config, which is the whole\n\t * reason the scheme is always `smtp://`.\n\t */\n\tprivate async connect({\n\t\tenvParser,\n\t}: ServiceRegisterOptions): Promise<EmailClient<TTemplates>> {\n\t\tconst { url, from } = envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.keys.url).string(),\n\t\t\t\tfrom: get(this.keys.from).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\treturn createEmailClient({\n\t\t\tsmtp: parseEmailUrl(url),\n\t\t\ttemplates: this.options.templates,\n\t\t\tdefaults: {\n\t\t\t\tfrom,\n\t\t\t\t...(this.options.replyTo ? { replyTo: this.options.replyTo } : {}),\n\t\t\t},\n\t\t});\n\t}\n}\n"],"mappings":";;;;;AAkDA,IAAa,QAAb,MAIA;CACC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;CAEjB,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,sCAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO;GACX,KAAK,qCAAW,WAAW,MAAM;GAIjC,MAAM,qCAAW,WAAW,OAAO;EACnC;AAGD,OAAK,UAAU;GACd,aAAa,qCAAW,UAAU;GAClC,UAAU,CAACC,cAAY,KAAK,QAAQA,UAAQ;EAC5C;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,IAAK;EACzC,CACD;CACD;;;;;;;;CASD,MAAc,QAAQ,EACrB,WACwB,EAAoC;EAC5D,MAAM,EAAE,KAAK,MAAM,GAAG,UACpB,OAAO,CAAC,SAAS;GACjB,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC,QAAQ;GAChC,MAAM,IAAI,KAAK,KAAK,KAAK,CAAC,QAAQ;EAClC,GAAE,CACF,OAAO;AAET,SAAO,4CAAkB;GACxB,MAAM,wCAAc,IAAI;GACxB,WAAW,KAAK,QAAQ;GACxB,UAAU;IACT;IACA,GAAI,KAAK,QAAQ,UAAU,EAAE,SAAS,KAAK,QAAQ,QAAS,IAAG,CAAE;GACjE;EACD,EAAC;CACF;AACD"}

package/dist/email.d.cts

@@ -0,0 +1,50 @@
+import { Construct } from "./construct-interface-D2nNkHUN.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";
+
+//#region src/email.d.ts
+
+interface EmailOptions<TTemplates extends TemplateRecord> {
+  /**
+   * The React templates this app can send.
+   *
+   * Structural — they are code, they ship with the handler, and which ones
+   * exist cannot differ between stages. They are also what types
+   * `sendTemplate`, so passing them here is what makes the client's call sites
+   * checkable.
+   */
+  templates: TTemplates;
+  /**
+   * A reply-to address for every send.
+   *
+   * `from` is deliberately absent: it belongs to the verified sending domain,
+   * which is `myapp.test` locally and the real domain deployed, so it arrives
+   * as stage config rather than being written here.
+   */
+  replyTo?: string;
+}
+declare class Email<TName extends string = string, TTemplates extends TemplateRecord = TemplateRecord> implements Construct<TName, EmailClient<TTemplates>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * build publishes and the key the client reads cannot drift.
+   */
+  private readonly keys;
+  constructor(id: ConstructName<TName>, options: EmailOptions<TTemplates>);
+  declare(): Declaration[];
+  /**
+   * Builds the client from the URL the adapter supplied.
+   *
+   * No provider branch and no driver lookup — `parseEmailUrl` turns any of
+   * Mailpit, SES, or Resend into the same transport config, which is the whole
+   * reason the scheme is always `smtp://`.
+   */
+  private connect;
+}
+//# sourceMappingURL=email.d.ts.map
+//#endregion
+export { Email, EmailOptions };
+//# sourceMappingURL=email.d.cts.map

package/dist/email.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.cts","names":[],"sources":["../src/email.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqD8B,UAvBb,YAuBa,CAAA,mBAvBmB,cAuBnB,CAAA,CAAA;EAAW;;;;;;;;EAYtB,SACsB,EA3B7B,UA2B6B;EAAU;;;AAb7B;;;;;;cAHT,wDAEO,iBAAiB,2BACxB,UAAU,OAAO,YAAY;;eAE5B;oBACK,QAAQ,aAAa,QAAQ,YAAY;;;;;;kBAStD,cAAc,iBACQ,aAAa;aAoB7B"}

package/dist/email.d.mts

@@ -0,0 +1,50 @@
+import { Construct } from "./construct-interface-BqwRNYA2.mjs";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";
+import { Service } from "@geekmidas/services";
+
+//#region src/email.d.ts
+
+interface EmailOptions<TTemplates extends TemplateRecord> {
+  /**
+   * The React templates this app can send.
+   *
+   * Structural — they are code, they ship with the handler, and which ones
+   * exist cannot differ between stages. They are also what types
+   * `sendTemplate`, so passing them here is what makes the client's call sites
+   * checkable.
+   */
+  templates: TTemplates;
+  /**
+   * A reply-to address for every send.
+   *
+   * `from` is deliberately absent: it belongs to the verified sending domain,
+   * which is `myapp.test` locally and the real domain deployed, so it arrives
+   * as stage config rather than being written here.
+   */
+  replyTo?: string;
+}
+declare class Email<TName extends string = string, TTemplates extends TemplateRecord = TemplateRecord> implements Construct<TName, EmailClient<TTemplates>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * build publishes and the key the client reads cannot drift.
+   */
+  private readonly keys;
+  constructor(id: ConstructName<TName>, options: EmailOptions<TTemplates>);
+  declare(): Declaration[];
+  /**
+   * Builds the client from the URL the adapter supplied.
+   *
+   * No provider branch and no driver lookup — `parseEmailUrl` turns any of
+   * Mailpit, SES, or Resend into the same transport config, which is the whole
+   * reason the scheme is always `smtp://`.
+   */
+  private connect;
+}
+//# sourceMappingURL=email.d.ts.map
+//#endregion
+export { Email, EmailOptions };
+//# sourceMappingURL=email.d.mts.map

package/dist/email.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.mts","names":[],"sources":["../src/email.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqD8B,UAvBb,YAuBa,CAAA,mBAvBmB,cAuBnB,CAAA,CAAA;EAAW;;;;;;;;EAYtB,SACsB,EA3B7B,UA2B6B;EAAU;;;AAb7B;;;;;;cAHT,wDAEO,iBAAiB,2BACxB,UAAU,OAAO,YAAY;;eAE5B;oBACK,QAAQ,aAAa,QAAQ,YAAY;;;;;;kBAStD,cAAc,iBACQ,aAAa;aAoB7B"}

package/dist/email.mjs

@@ -0,0 +1,58 @@
+import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
+import { createEmailClient, parseEmailUrl } from "@geekmidas/emailkit";
+
+//#region src/email.ts
+var Email = class {
+	id;
+	service;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the key the
+	* build publishes and the key the client reads cannot drift.
+	*/
+	keys;
+	constructor(id, options) {
+		this.options = options;
+		const canonical = canonicalId(id);
+		this.id = canonical;
+		this.keys = {
+			url: provideKey(canonical, "url"),
+			from: provideKey(canonical, "from")
+		};
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (options$1) => this.connect(options$1)
+		};
+	}
+	declare() {
+		return [{
+			kind: "email",
+			id: this.id,
+			provides: [this.keys.url, this.keys.from]
+		}];
+	}
+	/**
+	* Builds the client from the URL the adapter supplied.
+	*
+	* No provider branch and no driver lookup — `parseEmailUrl` turns any of
+	* Mailpit, SES, or Resend into the same transport config, which is the whole
+	* reason the scheme is always `smtp://`.
+	*/
+	async connect({ envParser }) {
+		const { url, from } = envParser.create((get) => ({
+			url: get(this.keys.url).string(),
+			from: get(this.keys.from).string()
+		})).parse();
+		return createEmailClient({
+			smtp: parseEmailUrl(url),
+			templates: this.options.templates,
+			defaults: {
+				from,
+				...this.options.replyTo ? { replyTo: this.options.replyTo } : {}
+			}
+		});
+	}
+};
+
+//#endregion
+export { Email };
+//# sourceMappingURL=email.mjs.map

package/dist/email.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.mjs","names":["id: ConstructName<TName>","options: EmailOptions<TTemplates>","options"],"sources":["../src/email.ts"],"sourcesContent":["/**\n * `Email` — declared outbound mail.\n *\n * The same three-package meeting point as `ObjectStorage`: it implements the\n * construct contract, derives its env key through `@geekmidas/manifest`, and\n * hands back an `@geekmidas/emailkit` client. It names no provider — locally the\n * injected URL points at Mailpit, deployed it points at SES or whichever service\n * config selected.\n *\n * Where object storage needs a driver per provider, this needs none: mail is\n * delivered over SMTP whoever delivers it, so there is one client and one URL\n * shape, and the provider survives only as a host and a credential.\n */\n\nimport {\n\tcreateEmailClient,\n\ttype EmailClient,\n\tparseEmailUrl,\n\ttype TemplateRecord,\n} from '@geekmidas/emailkit';\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 { Construct } from './construct-interface';\n\nexport interface EmailOptions<TTemplates extends TemplateRecord> {\n\t/**\n\t * The React templates this app can send.\n\t *\n\t * Structural — they are code, they ship with the handler, and which ones\n\t * exist cannot differ between stages. They are also what types\n\t * `sendTemplate`, so passing them here is what makes the client's call sites\n\t * checkable.\n\t */\n\ttemplates: TTemplates;\n\t/**\n\t * A reply-to address for every send.\n\t *\n\t * `from` is deliberately absent: it belongs to the verified sending domain,\n\t * which is `myapp.test` locally and the real domain deployed, so it arrives\n\t * as stage config rather than being written here.\n\t */\n\treplyTo?: string;\n}\n\nexport class Email<\n\tTName extends string = string,\n\tTTemplates extends TemplateRecord = TemplateRecord,\n> implements Construct<TName, EmailClient<TTemplates>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { url: string; from: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: EmailOptions<TTemplates>,\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\t// The sending identity travels with the URL rather than being a second\n\t\t\t// construct option, for the same reason the URL does: it is the one\n\t\t\t// thing about mail that differs per stage.\n\t\t\tfrom: provideKey(canonical, 'from'),\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: (options) => this.connect(options),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'email',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.url, this.keys.from],\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds the client from the URL the adapter supplied.\n\t *\n\t * No provider branch and no driver lookup — `parseEmailUrl` turns any of\n\t * Mailpit, SES, or Resend into the same transport config, which is the whole\n\t * reason the scheme is always `smtp://`.\n\t */\n\tprivate async connect({\n\t\tenvParser,\n\t}: ServiceRegisterOptions): Promise<EmailClient<TTemplates>> {\n\t\tconst { url, from } = envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.keys.url).string(),\n\t\t\t\tfrom: get(this.keys.from).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\treturn createEmailClient({\n\t\t\tsmtp: parseEmailUrl(url),\n\t\t\ttemplates: this.options.templates,\n\t\t\tdefaults: {\n\t\t\t\tfrom,\n\t\t\t\t...(this.options.replyTo ? { replyTo: this.options.replyTo } : {}),\n\t\t\t},\n\t\t});\n\t}\n}\n"],"mappings":";;;;AAkDA,IAAa,QAAb,MAIA;CACC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;CAEjB,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,YAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO;GACX,KAAK,WAAW,WAAW,MAAM;GAIjC,MAAM,WAAW,WAAW,OAAO;EACnC;AAGD,OAAK,UAAU;GACd,aAAa,WAAW,UAAU;GAClC,UAAU,CAACC,cAAY,KAAK,QAAQA,UAAQ;EAC5C;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,IAAK;EACzC,CACD;CACD;;;;;;;;CASD,MAAc,QAAQ,EACrB,WACwB,EAAoC;EAC5D,MAAM,EAAE,KAAK,MAAM,GAAG,UACpB,OAAO,CAAC,SAAS;GACjB,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC,QAAQ;GAChC,MAAM,IAAI,KAAK,KAAK,KAAK,CAAC,QAAQ;EAClC,GAAE,CACF,OAAO;AAET,SAAO,kBAAkB;GACxB,MAAM,cAAc,IAAI;GACxB,WAAW,KAAK,QAAQ;GACxB,UAAU;IACT;IACA,GAAI,KAAK,QAAQ,UAAU,EAAE,SAAS,KAAK,QAAQ,QAAS,IAAG,CAAE;GACjE;EACD,EAAC;CACF;AACD"}