@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/email/transports/email-transport.js

@@ -0,0 +1,241 @@
+"use strict";
+// =============================================================================
+// Email transports: the `email-transport` pluggable kind (PP-14.8)
+// =============================================================================
+//
+// A transport is the part of the email slice that knows ONE way of putting a
+// rendered message on the network: Amazon SES, an SMTP relay, a hosted API
+// (SendGrid, Postmark), a file or a log for local development. The slice itself
+// (the notification channel, the admin "Send test email") only ever talks to an
+// `EmailTransport`; which one was built, with which settings and secrets, is
+// runtime configuration an administrator edits at /admin/settings/email.
+//
+//   definition   id + label + settingsSchema + defaults + secrets   (what a form needs)
+//   operations   build() -> EmailTransport { send, verify?, destroy? }
+//
+// `ses` and `smtp` register through `registerEmailTransport` exactly as an
+// app's transport does (`./builtin-email-transports.ts`): no private fast path.
+//
+// FRAMEWORK-LIGHT, AND A LEAF: this file imports the pluggable-kind primitive,
+// the credential purpose registry and types. The settings service, the Doctor
+// and the template import it without pulling an SDK in; the built-ins' SDK
+// imports live in their own files.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emailTransportKind = void 0;
+exports.emailTransportCredentialPurpose = emailTransportCredentialPurpose;
+exports.registerEmailTransport = registerEmailTransport;
+exports.emailTransportDefinitions = emailTransportDefinitions;
+exports.emailTransportIds = emailTransportIds;
+exports.getEmailTransport = getEmailTransport;
+exports.requireEmailTransport = requireEmailTransport;
+exports.labelOfEmailTransport = labelOfEmailTransport;
+exports.emailTransportSecretAddress = emailTransportSecretAddress;
+exports.describeEmailTransports = describeEmailTransports;
+exports.missingEmailTransportFields = missingEmailTransportFields;
+const email_1 = require("@marinoscar/platform-contract/email");
+const index_1 = require("../../core/index");
+const index_2 = require("../../credentials/index");
+/**
+ * The `email-transport` pluggable kind. Its implementations are the
+ * {@link EmailTransportDefinition}s themselves. Use
+ * {@link registerEmailTransport} and the helpers below rather than the kind
+ * directly.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+exports.emailTransportKind = (0, index_1.definePluggableKind)({
+    kind: 'email-transport',
+    label: 'Email transport',
+});
+/** Setting names that look like a secret: a secret is declared in `secrets`, never a setting. */
+const SECRET_LOOKING_FIELDS = new Set([
+    'secretAccessKey',
+    'secretKey',
+    'sessionToken',
+    'secret',
+    'password',
+    'smtpPassword',
+    'apiKey',
+    'apiKeys',
+    'key',
+    'token',
+    'privateKey',
+].map((name) => name.toLowerCase()));
+/**
+ * The credential purpose a transport's secrets use by default (`email_<id>`).
+ *
+ * @param id - the transport id.
+ * @stability experimental
+ */
+function emailTransportCredentialPurpose(id) {
+    return `email_${id}`;
+}
+function assertValidDefinition(def) {
+    const where = `Email transport "${def.id}"`;
+    if (typeof def.id !== 'string' || !email_1.EMAIL_TRANSPORT_ID_PATTERN.test(def.id)) {
+        throw new Error(`Invalid email transport id ${JSON.stringify(def.id)}: it must match ${email_1.EMAIL_TRANSPORT_ID_PATTERN}.`);
+    }
+    if (typeof def.label !== 'string' || def.label.trim() === '')
+        throw new Error(`${where}: label must be a non-empty string.`);
+    if (typeof def.build !== 'function')
+        throw new Error(`${where}: build must be a function.`);
+    for (const hook of ['credentialAddress', 'missing', 'summary', 'egressHosts']) {
+        if (def[hook] !== undefined && typeof def[hook] !== 'function')
+            throw new Error(`${where}: ${hook} must be a function.`);
+    }
+    if (typeof def.settingsSchema !== 'object' || def.settingsSchema === null || typeof def.settingsSchema.shape !== 'object') {
+        throw new Error(`${where}: settingsSchema must be a z.object(...).`);
+    }
+    for (const field of Object.keys(def.settingsSchema.shape)) {
+        if (SECRET_LOOKING_FIELDS.has(field.toLowerCase())) {
+            throw new Error(`${where}: settingsSchema declares "${field}", which looks like a secret. A secret is never a setting: ` +
+                'declare it in `secrets`; it is stored encrypted in the credential store.');
+        }
+    }
+    const parsedDefaults = def.settingsSchema.safeParse(def.defaults);
+    if (!parsedDefaults.success) {
+        throw new Error(`${where}: defaults do not parse with settingsSchema: ` +
+            parsedDefaults.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; '));
+    }
+}
+/**
+ * Registers an email transport. Call it at import time, before the
+ * application bootstraps (the reference app does it from
+ * `apps/api/src/app-registrations/email.ts`, which `platform/email/email.config.ts`
+ * imports first). `ses` and `smtp` register through this same function.
+ *
+ * Registering is all it takes: `GET /api/email-settings` describes the
+ * transport (`descriptors`, and a generated form on the admin page), its
+ * settings are stored under `transports.<id>` and validated by its
+ * `settingsSchema`, its secrets get a credential purpose (`email_<id>`) unless
+ * `credentialAddress` names one, and once an administrator selects it every
+ * email the application sends (notifications, broadcasts, the admin test)
+ * goes through the transport it builds.
+ *
+ * @param def - the transport.
+ * @throws Error when the definition is malformed (an id that does not match the pattern, a secret-looking settings field, defaults that do not parse, a missing `build`).
+ * @throws RegistryError `DUPLICATE_ID` when the id is registered, `FROZEN` after the application bootstrapped.
+ *
+ * @example
+ * ```ts
+ * registerEmailTransport({
+ *   id: 'sendgrid',
+ *   label: 'SendGrid',
+ *   settingsSchema: z.object({ apiBase: z.string().describe('API base URL') }),
+ *   defaults: { apiBase: 'https://api.sendgrid.com' },
+ *   secrets: [{ name: 'apiKey', label: 'API key', required: true }],
+ *   build: ({ settings, secret, logger, classifyRateLimit }) =>
+ *     new SendgridTransport(settings.apiBase, () => secret('apiKey'), logger, classifyRateLimit),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+function registerEmailTransport(def) {
+    assertValidDefinition(def);
+    const purpose = emailTransportCredentialPurpose(def.id);
+    const ownsPurpose = (def.secrets ?? []).length > 0 && def.credentialAddress === undefined;
+    if (ownsPurpose && index_2.credentialPurposeRegistry.has(purpose)) {
+        throw new Error(`Email transport "${def.id}": the credential purpose "${purpose}" is already registered by another owner. Pick another transport id.`);
+    }
+    // The definition itself is the registered implementation, so the hooks
+    // (`missing`, `summary`, ...) travel with it.
+    exports.emailTransportKind.register(def);
+    if (ownsPurpose) {
+        (0, index_2.registerCredentialPurpose)({ purpose, owner: 'email', label: `${def.label} secrets`, tiers: ['system'] });
+    }
+}
+/**
+ * Every registered email transport, in registration order (the built-ins
+ * first; the order the admin page lists them).
+ *
+ * @stability experimental
+ */
+function emailTransportDefinitions() {
+    return exports.emailTransportKind.list();
+}
+/**
+ * The ids of every registered email transport, in registration order.
+ *
+ * @stability experimental
+ */
+function emailTransportIds() {
+    return exports.emailTransportKind.ids();
+}
+/**
+ * The transport registered under `id`, or `undefined`.
+ *
+ * @param id - the transport id.
+ * @stability experimental
+ */
+function getEmailTransport(id) {
+    return exports.emailTransportKind.has(id) ? exports.emailTransportKind.get(id) : undefined;
+}
+/**
+ * The transport registered under `id`.
+ *
+ * @param id - the transport id.
+ * @throws PluggableUnknownError when none is registered; the message names the registered ids.
+ * @stability experimental
+ */
+function requireEmailTransport(id) {
+    return exports.emailTransportKind.get(id);
+}
+/** The labels of the shipped transports, for a caller that renders before they register (a template test). */
+const BUILTIN_LABELS = { ses: 'Amazon SES', smtp: 'SMTP' };
+/**
+ * The human label of a transport: its registered label, else the shipped
+ * label of a built-in, else the id itself. What the Doctor, the egress view and
+ * the test email name it by.
+ *
+ * @param id - the transport id.
+ * @stability experimental
+ */
+function labelOfEmailTransport(id) {
+    return getEmailTransport(id)?.label ?? BUILTIN_LABELS[id] ?? id;
+}
+/**
+ * Where `transport`'s secret `name` lives in the credential store.
+ *
+ * @param transport - a registered transport.
+ * @param name - one of the secrets it declares.
+ * @returns the `(purpose, name)` address.
+ * @stability experimental
+ */
+function emailTransportSecretAddress(transport, name) {
+    const label = transport.secrets?.find((spec) => spec.name === name)?.label ?? name;
+    if (transport.credentialAddress) {
+        const address = transport.credentialAddress(name);
+        return { purpose: address.purpose, name: address.name, label: address.label ?? label };
+    }
+    return { purpose: emailTransportCredentialPurpose(transport.id), name, label };
+}
+/**
+ * The descriptor of every registered transport for a generated form: its
+ * non-secret fields, then one write-only `secret` field per declared secret
+ * carrying only whether a value is stored.
+ *
+ * @param presence - which of a transport's secrets are stored.
+ * @stability experimental
+ */
+function describeEmailTransports(presence) {
+    return exports.emailTransportKind.describeAll(presence);
+}
+/**
+ * The names of a transport's still-missing settings and secrets
+ * ({@link EmailTransportDefinition.missing}, or every required secret that is absent).
+ *
+ * @param transport - a registered transport.
+ * @param settings - its parsed settings.
+ * @param present - which of its declared secrets are stored.
+ * @stability experimental
+ */
+function missingEmailTransportFields(transport, settings, present) {
+    if (transport.missing)
+        return transport.missing(settings, present);
+    return (transport.secrets ?? []).filter((secret) => secret.required && present[secret.name] !== true).map((secret) => secret.label);
+}
+//# sourceMappingURL=email-transport.js.map

package/dist/email/transports/email-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-transport.js","sourceRoot":"","sources":["../../../src/email/transports/email-transport.ts"],"names":[],"mappings":"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"}

package/dist/email/transports/email-transport.resolver.d.ts

@@ -0,0 +1,75 @@
+import type { OnModuleDestroy } from '@nestjs/common';
+import { CredentialsService } from '../../credentials/index';
+import { type ResolvedEmailModuleOptions } from '../email.options';
+import type { EmailSettings } from '../email-settings.schema';
+import type { EmailMessage, EmailSendResult } from '../email.types';
+import { type EmailTransport } from './email-transport';
+import './builtin-email-transports';
+/**
+ * An email transport ready to send with.
+ *
+ * @stability experimental
+ */
+export interface ActiveEmailTransport {
+    /** Discriminant: the transport resolved. */
+    ok: true;
+    /** The transport id (`settings.provider`). */
+    id: string;
+    /** Its human label. */
+    label: string;
+    /** The built transport. */
+    transport: EmailTransport;
+}
+/**
+ * Why no transport could be resolved.
+ *
+ * @stability experimental
+ */
+export interface UnavailableEmailTransport {
+    /** Discriminant: the transport did not resolve. */
+    ok: false;
+    /** A sentence an administrator can act on (no secret, no stored value). */
+    error: string;
+}
+/**
+ * The outcome of {@link EmailTransportResolver.resolve}: the transport, or why there is none.
+ *
+ * @stability experimental
+ */
+export type EmailTransportResolution = ActiveEmailTransport | UnavailableEmailTransport;
+/**
+ * Resolves and caches the active email transport. Cheap to call per send: the
+ * transport is rebuilt only when its id or settings change (the previous one
+ * is `destroy()`ed), and a transport reads its secrets itself, at send time,
+ * through `build`'s `secret(name)`, so a rotated secret takes effect on the
+ * next send.
+ *
+ * @stability experimental
+ */
+export declare class EmailTransportResolver implements OnModuleDestroy {
+    private readonly credentials;
+    private readonly logger;
+    private readonly options;
+    /** Transport id to the last transport built for it and the fingerprint of its settings. */
+    private readonly cache;
+    constructor(credentials: CredentialsService, options?: Pick<ResolvedEmailModuleOptions, 'classifyRateLimit' | 'sesRegionFallback'>);
+    /**
+     * The transport the settings select.
+     *
+     * @param settings - the stored email settings (`provider`, `transports`).
+     * @returns the built transport, or `{ ok: false, error }` when `provider` is unset or names a transport nobody registered, its stored settings do not parse, or `build` throws.
+     */
+    resolve(settings: Pick<EmailSettings, 'provider' | 'transports'>): Promise<EmailTransportResolution>;
+    /**
+     * Resolves the transport the settings select and sends `message` through it.
+     * NEVER THROWS: a transport that cannot be resolved is a failed result.
+     *
+     * @param settings - the stored email settings.
+     * @param message - the finished message.
+     */
+    send(settings: Pick<EmailSettings, 'provider' | 'transports'>, message: EmailMessage): Promise<EmailSendResult>;
+    /** Releases every cached transport. */
+    onModuleDestroy(): Promise<void>;
+    private release;
+}
+//# sourceMappingURL=email-transport.resolver.d.ts.map

package/dist/email/transports/email-transport.resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-transport.resolver.d.ts","sourceRoot":"","sources":["../../../src/email/transports/email-transport.resolver.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAA6C,KAAK,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,4BAA4B,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,EAAE,EAAE,IAAI,CAAC;IACT,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,EAAE,EAAE,KAAK,CAAC;IACV,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,GAAG,yBAAyB,CAAC;AAUxF;;;;;;;;GAQG;AACH,qBACa,sBAAuB,YAAW,eAAe;IAQ1D,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8E;IAEtG,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyE;gBAG5E,WAAW,EAAE,kBAAkB,EACb,OAAO,CAAC,EAAE,IAAI,CAAC,0BAA0B,EAAE,mBAAmB,GAAG,mBAAmB,CAAC;IAK1H;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAyD1G;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,YAAY,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAMrH,uCAAuC;IACjC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;YAMxB,OAAO;CAOtB"}

package/dist/email/transports/email-transport.resolver.js

@@ -0,0 +1,164 @@
+"use strict";
+// =============================================================================
+// EmailTransportResolver: the settings' `provider`, as a built transport (PP-14.8)
+// =============================================================================
+//
+// The one place that turns "this stored email configuration" into a runnable
+// `EmailTransport`: it finds the implementation in the registry, parses that
+// transport's own settings, hands `build` a resolver for its declared secrets
+// and caches the result until the settings change. The notification channel
+// and the admin "Send test email" depend on THIS, never on a concrete SES or
+// SMTP class, so a transport an app registered is used by both with no edit to
+// either.
+//
+// PROVIDED ONCE, in `EmailModule`, and exported: a consumer writes
+// `imports: [EmailModule]` and injects it. (Overriding a provider token in an
+// app module never reached the package consumers; registering a transport does.)
+//
+// IT NEVER THROWS for a configuration problem. A transport nobody registered,
+// settings that no longer parse and a `build` that throws all come back as
+// `{ ok: false, error }`, the same shape every other pre-send refusal has, so
+// a caller maps them to its own failure result without a try/catch.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailTransportResolver = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const index_2 = require("../../credentials/index");
+const email_options_1 = require("../email.options");
+const email_settings_compat_1 = require("../email-settings-compat");
+const email_transport_1 = require("./email-transport");
+// The built-in transports register on import: whatever resolves a transport by id finds them.
+require("./builtin-email-transports");
+/** Longest error text a resolution failure carries. */
+const MAX_ERROR_LENGTH = 500;
+function describe(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return text.length > MAX_ERROR_LENGTH ? `${text.slice(0, MAX_ERROR_LENGTH)}…` : text;
+}
+/**
+ * Resolves and caches the active email transport. Cheap to call per send: the
+ * transport is rebuilt only when its id or settings change (the previous one
+ * is `destroy()`ed), and a transport reads its secrets itself, at send time,
+ * through `build`'s `secret(name)`, so a rotated secret takes effect on the
+ * next send.
+ *
+ * @stability experimental
+ */
+let EmailTransportResolver = class EmailTransportResolver {
+    credentials;
+    logger = new common_1.Logger('EmailTransports');
+    options;
+    /** Transport id to the last transport built for it and the fingerprint of its settings. */
+    cache = new Map();
+    constructor(credentials, options) {
+        this.credentials = credentials;
+        this.options = options ?? email_options_1.UNCONFIGURED_EMAIL_OPTIONS;
+    }
+    /**
+     * The transport the settings select.
+     *
+     * @param settings - the stored email settings (`provider`, `transports`).
+     * @returns the built transport, or `{ ok: false, error }` when `provider` is unset or names a transport nobody registered, its stored settings do not parse, or `build` throws.
+     */
+    async resolve(settings) {
+        const id = settings.provider;
+        if (!id)
+            return { ok: false, error: 'No email provider is configured.' };
+        if (!email_transport_1.emailTransportKind.has(id)) {
+            return {
+                ok: false,
+                error: `Email transport "${id}" is not registered (registered: ${email_transport_1.emailTransportKind.ids().join(', ') || '(none)'}). ` +
+                    'Choose another transport at /admin/settings/email, or register it with registerEmailTransport.',
+            };
+        }
+        const definition = email_transport_1.emailTransportKind.get(id);
+        let parsed;
+        try {
+            parsed = email_transport_1.emailTransportKind.parseSettings(id, (0, email_settings_compat_1.storedTransportSettings)(settings, id));
+        }
+        catch (error) {
+            if (error instanceof index_1.PluggableSettingsError) {
+                const fields = [...new Set(error.issues.map((issue) => issue.path.join('.') || '(root)'))].join(', ');
+                return { ok: false, error: `The stored settings of email transport "${id}" are invalid at: ${fields}. Save the email configuration again.` };
+            }
+            return { ok: false, error: describe(error) };
+        }
+        const fingerprint = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(parsed)).digest('hex');
+        const cached = this.cache.get(id);
+        if (cached?.fingerprint === fingerprint) {
+            return { ok: true, id, label: definition.label, transport: cached.transport };
+        }
+        let transport;
+        try {
+            transport = await definition.build({
+                logger: new common_1.Logger(`EmailTransport:${id}`),
+                ...(this.options.classifyRateLimit ? { classifyRateLimit: this.options.classifyRateLimit } : {}),
+                sesRegionFallback: this.options.sesRegionFallback,
+                settings: parsed,
+                secret: async (name) => {
+                    const address = (0, email_transport_1.emailTransportSecretAddress)(definition, name);
+                    return this.credentials.getSecret(address.purpose, address.name);
+                },
+            });
+        }
+        catch (error) {
+            return { ok: false, error: `Email transport "${id}" could not be built: ${describe(error)}` };
+        }
+        // Read AGAIN after the await: a concurrent resolve may have replaced the
+        // entry meanwhile, and the transport actually superseded is that one.
+        const superseded = this.cache.get(id);
+        this.cache.set(id, { fingerprint, transport });
+        if (superseded)
+            await this.release(id, superseded.transport);
+        return { ok: true, id, label: definition.label, transport };
+    }
+    /**
+     * Resolves the transport the settings select and sends `message` through it.
+     * NEVER THROWS: a transport that cannot be resolved is a failed result.
+     *
+     * @param settings - the stored email settings.
+     * @param message - the finished message.
+     */
+    async send(settings, message) {
+        const resolved = await this.resolve(settings);
+        if (!resolved.ok)
+            return { success: false, error: resolved.error };
+        return resolved.transport.send(message);
+    }
+    /** Releases every cached transport. */
+    async onModuleDestroy() {
+        const entries = [...this.cache.entries()];
+        this.cache.clear();
+        await Promise.all(entries.map(([id, entry]) => this.release(id, entry.transport)));
+    }
+    async release(id, transport) {
+        try {
+            await transport.destroy?.();
+        }
+        catch (error) {
+            this.logger.warn(`Email transport "${id}" failed to release its resources: ${describe(error)}`);
+        }
+    }
+};
+exports.EmailTransportResolver = EmailTransportResolver;
+exports.EmailTransportResolver = EmailTransportResolver = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(email_options_1.EMAIL_OPTIONS)),
+    __metadata("design:paramtypes", [index_2.CredentialsService, Object])
+], EmailTransportResolver);
+//# sourceMappingURL=email-transport.resolver.js.map

package/dist/email/transports/email-transport.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-transport.resolver.js","sourceRoot":"","sources":["../../../src/email/transports/email-transport.resolver.ts"],"names":[],"mappings":"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"}

package/dist/exports/csv.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The UTF-8 byte order mark, as the one character it encodes. Written once at
+ * the start of each CSV file.
+ *
+ * @example
+ * ```ts
+ * const header = UTF8_BOM + csvRecord(['id', 'name']) + '\r\n';
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export declare const UTF8_BOM = "\uFEFF";
+/**
+ * What a spreadsheet treats as the start of a formula: `=`, `+`, `-`, `@`, a
+ * tab or a carriage return.
+ *
+ * @stability stable
+ */
+export declare const FORMULA_TRIGGER: RegExp;
+/**
+ * The record separator RFC 4180 prescribes.
+ *
+ * @stability stable
+ */
+export declare const CSV_LINE_END = "\r\n";
+/**
+ * One field, quoted when RFC 4180 requires it (a `"`, `,`, CR or LF inside),
+ * with its quotes doubled.
+ *
+ * @param text - the field's text.
+ * @returns the field as it goes into a record.
+ *
+ * @example
+ * ```ts
+ * csvField('a,b'); // '"a,b"'
+ * csvField('say "hi"'); // '"say ""hi"""'
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export declare function csvField(text: string): string;
+/**
+ * `text` prefixed with `'` when a spreadsheet would read it as a formula.
+ * Apply it to text cells only; numbers keep their sign.
+ *
+ * @param text - a text cell.
+ * @returns the neutralised text.
+ *
+ * @example
+ * ```ts
+ * neutralizeFormula('=HYPERLINK("x")'); // "'=HYPERLINK(\"x\")"
+ * neutralizeFormula('hello'); // 'hello'
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export declare function neutralizeFormula(text: string): string;
+/**
+ * One CSV record, without its line ending.
+ *
+ * @param fields - the already-quoted fields ({@link csvField}).
+ * @returns the fields joined by `,`.
+ *
+ * @example
+ * ```ts
+ * csvRecord(['1', csvField('a,b')]) + CSV_LINE_END; // '1,"a,b"\r\n'
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export declare function csvRecord(fields: readonly string[]): string;
+/**
+ * One typed value as a CSV field: `null` is empty, a number or boolean is its
+ * text, and any other text is formula-neutralised unless `numeric` says the
+ * column holds numbers, then quoted as needed.
+ *
+ * @param value - the cell.
+ * @param numeric - whether the column is numeric (never neutralised).
+ * @returns the field.
+ *
+ * @example
+ * ```ts
+ * csvCell('-5', true); // '-5'
+ * csvCell('-5', false); // "'-5"
+ * csvCell(null, false); // ''
+ * ```
+ *
+ * @stability stable
+ */
+export declare function csvCell(value: string | number | boolean | null | undefined, numeric: boolean): string;
+//# sourceMappingURL=csv.d.ts.map

package/dist/exports/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/exports/csv.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,WAAM,CAAC;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAiB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAIrG"}