@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/esm/email/schemas.d.ts

@@ -0,0 +1,276 @@
+import { z } from 'zod';
+import type { BuiltinEmailProviderKind } from './constants.js';
+/**
+ * The entries of the former transport enum: each built-in kind keyed by itself.
+ *
+ * @deprecated The transport is an open id now ({@link emailTransportIdSchema}).
+ * @stability stable
+ */
+export type EmailProviderKindEnum = {
+    [K in BuiltinEmailProviderKind]: K;
+};
+/**
+ * An email transport id: any string matching {@link EMAIL_TRANSPORT_ID_PATTERN}.
+ * Not an enum: an app registers transports (`registerEmailTransport`), and the
+ * API validates the id against the registry.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare const emailTransportIdSchema: z.ZodString;
+/**
+ * One transport's non-secret settings as stored: whatever that transport's
+ * `settingsSchema` declares. The contract cannot see the registry, so it
+ * checks the shape (a record) and the API validates each entry with the
+ * transport that owns it.
+ *
+ * @stability experimental
+ */
+export declare const emailTransportSettingsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/**
+ * The `transports` record: transport id to that transport's settings.
+ *
+ * @stability experimental
+ */
+export declare const emailTransportsSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/**
+ * The `transports` record of a PUT: `null` removes a transport's stored
+ * settings (back to its defaults), an object is merged over them.
+ *
+ * @stability experimental
+ */
+export declare const emailTransportsPatchSchema: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+/**
+ * The admin-configurable half of email delivery: which transport, where it
+ * lives, who the mail claims to be from. Ordinary configuration, safe to
+ * return from an admin endpoint; stored in the `email` row of
+ * `system_settings`.
+ *
+ * @stability stable
+ */
+export declare const emailSettingsSchema: z.ZodObject<{
+    provider: z.ZodNullable<z.ZodString>;
+    enabled: z.ZodBoolean;
+    transports: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    sesRegion: z.ZodOptional<z.ZodString>;
+    sesAccessKeyId: z.ZodOptional<z.ZodString>;
+    smtpHost: z.ZodOptional<z.ZodString>;
+    smtpPort: z.ZodOptional<z.ZodNumber>;
+    smtpUseTls: z.ZodOptional<z.ZodBoolean>;
+    smtpUsername: z.ZodOptional<z.ZodString>;
+    fromAddress: z.ZodOptional<z.ZodEmail>;
+    fromName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Validated email settings.
+ *
+ * @stability stable
+ */
+export type EmailSettings = z.infer<typeof emailSettingsSchema>;
+/**
+ * What a system with no email configuration reads as: no transport, switched
+ * off.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_EMAIL_SETTINGS: EmailSettings;
+/**
+ * What the admin page knows about a stored secret (the SMTP password, the SES
+ * secret access key) without being told the secret: whether it is set, the
+ * store's mask, and when and by whom it was last written.
+ *
+ * @stability stable
+ */
+export declare const credentialStatusSchema: z.ZodObject<{
+    configured: z.ZodBoolean;
+    hint: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    updatedByUserId: z.ZodNullable<z.ZodUUID>;
+}, z.core.$strip>;
+/**
+ * The masked status of one stored secret.
+ *
+ * @stability stable
+ */
+export type EmailCredentialStatusDto = z.infer<typeof credentialStatusSchema>;
+/**
+ * The `GET` and `PUT /api/email-settings` response body (inside the global
+ * `{ data }` envelope): the settings, a descriptor per registered transport,
+ * the masked status of every transport secret, why
+ * the stored row could not be read (field paths only; the read degrades to
+ * the defaults instead of failing, so the page that repairs the row still
+ * renders), and the row's version for `If-Match`.
+ *
+ * @stability stable
+ */
+export declare const emailSettingsResponseSchema: z.ZodObject<{
+    provider: z.ZodNullable<z.ZodString>;
+    enabled: z.ZodBoolean;
+    sesRegion: z.ZodOptional<z.ZodString>;
+    sesAccessKeyId: z.ZodOptional<z.ZodString>;
+    smtpHost: z.ZodOptional<z.ZodString>;
+    smtpPort: z.ZodOptional<z.ZodNumber>;
+    smtpUseTls: z.ZodOptional<z.ZodBoolean>;
+    smtpUsername: z.ZodOptional<z.ZodString>;
+    fromAddress: z.ZodOptional<z.ZodEmail>;
+    fromName: z.ZodOptional<z.ZodString>;
+    transports: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    descriptors: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"boolean">;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"enum">;
+            options: z.ZodArray<z.ZodString>;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"number">;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            integer: z.ZodOptional<z.ZodBoolean>;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"string">;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"other">;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"secret">;
+            hasValue: z.ZodBoolean;
+            required: z.ZodBoolean;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>;
+    secretStatuses: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+        configured: z.ZodBoolean;
+        hint: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+        updatedByUserId: z.ZodNullable<z.ZodUUID>;
+    }, z.core.$strip>>>;
+    smtpPasswordStatus: z.ZodObject<{
+        configured: z.ZodBoolean;
+        hint: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+        updatedByUserId: z.ZodNullable<z.ZodUUID>;
+    }, z.core.$strip>;
+    sesSecretAccessKeyStatus: z.ZodObject<{
+        configured: z.ZodBoolean;
+        hint: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+        updatedByUserId: z.ZodNullable<z.ZodUUID>;
+    }, z.core.$strip>;
+    settingsError: z.ZodNullable<z.ZodString>;
+    version: z.ZodNumber;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    updatedBy: z.ZodNullable<z.ZodObject<{
+        id: z.ZodUUID;
+        email: z.ZodEmail;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The GET/PUT response body, as sent.
+ *
+ * @stability stable
+ */
+export type EmailSettingsResponse = z.infer<typeof emailSettingsResponseSchema>;
+/**
+ * The `PUT /api/email-settings` body: every settings field (blankable), the
+ * `transports` patch, plus the WRITE-ONLY secrets (`secrets`, and the two
+ * legacy aliases). A blank secret (absent, `null` or `''`)
+ * preserves the stored one; erasing a stored secret is not expressible here.
+ *
+ * @stability stable
+ */
+export declare const updateEmailSettingsSchema: z.ZodObject<{
+    provider: z.ZodNullable<z.ZodString>;
+    enabled: z.ZodBoolean;
+    transports: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    sesRegion: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodString>]>;
+    sesAccessKeyId: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodString>]>;
+    smtpHost: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodString>]>;
+    smtpPort: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodNumber>]>;
+    smtpUseTls: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodBoolean>]>;
+    smtpUsername: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodString>]>;
+    fromAddress: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodEmail>]>;
+    fromName: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodNull]>, z.ZodOptional<z.ZodString>]>;
+    smtpPassword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sesSecretAccessKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNullable<z.ZodString>>>>>;
+}, z.core.$strip>;
+/**
+ * The parsed PUT body, secrets included.
+ *
+ * @stability stable
+ */
+export type UpdateEmailSettingsInput = z.infer<typeof updateEmailSettingsSchema>;
+/**
+ * The `POST /api/email-settings/test` response body. HTTP 200 even when the
+ * send failed: read `success`, and show `error`, the provider's own message
+ * (already redacted of every credential and length-capped by the API).
+ *
+ * @stability stable
+ */
+export declare const testEmailResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    sentTo: z.ZodEmail;
+    providerKind: z.ZodNullable<z.ZodString>;
+    messageId: z.ZodNullable<z.ZodString>;
+    error: z.ZodNullable<z.ZodString>;
+    attemptedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * The POST /test response body.
+ *
+ * @stability stable
+ */
+export type TestEmailResult = z.infer<typeof testEmailResultSchema>;
+/**
+ * The field names no email settings shape may declare (the compile-time
+ * proofs below check against them).
+ *
+ * @stability stable
+ */
+export type EmailSecretFieldName = 'smtpPassword' | 'password' | 'secret' | 'apiKey' | 'accessKeyId' | 'secretAccessKey' | 'ciphertext';
+/**
+ * `true` while {@link EmailSettings} has no secret-named field; `never` otherwise.
+ *
+ * @stability stable
+ */
+export type EmailSettingsCarriesNoSecret = Extract<keyof EmailSettings, EmailSecretFieldName> extends never ? true : never;
+/**
+ * The proof that {@link EmailSettings} carries no secret (fails to compile otherwise).
+ *
+ * @stability stable
+ */
+export declare const EMAIL_SETTINGS_CARRIES_NO_SECRET: EmailSettingsCarriesNoSecret;
+/**
+ * `true` while {@link EmailSettingsResponse} has no secret-named field; `never` otherwise.
+ *
+ * @stability stable
+ */
+export type EmailSettingsResponseCarriesNoSecret = Extract<keyof EmailSettingsResponse, EmailSecretFieldName> extends never ? true : never;
+/**
+ * The proof that {@link EmailSettingsResponse} carries no secret (fails to compile otherwise).
+ *
+ * @stability stable
+ */
+export declare const EMAIL_SETTINGS_RESPONSE_CARRIES_NO_SECRET: EmailSettingsResponseCarriesNoSecret;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/esm/email/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/email/schemas.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;KAAG,CAAC,IAAI,wBAAwB,GAAG,CAAC;CAAE,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,aAA+C,CAAC;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,wCAAoC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,kEAAiE,CAAC;AAEpG;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,iFAA4E,CAAC;AAKpH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;iBA6D9B,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAGpC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;iBASjC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE9E;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmCtC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAqBhF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;iBAkCpC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;iBAahC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAYpE;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B,cAAc,GACd,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,aAAa,GACb,iBAAiB,GACjB,YAAY,CAAC;AAEjB;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAAC,MAAM,aAAa,EAAE,oBAAoB,CAAC,SAAS,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAE3H;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,4BAAmC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,oCAAoC,GAC9C,OAAO,CAAC,MAAM,qBAAqB,EAAE,oBAAoB,CAAC,SAAS,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAE1F;;;;GAIG;AACH,eAAO,MAAM,yCAAyC,EAAE,oCAA2C,CAAC"}

package/dist/esm/email/schemas.js

@@ -0,0 +1,277 @@
+// =============================================================================
+// Email: the wire contract of `/api/email-settings` (issue #737, PP-8.4;
+// shapes from #122, #124 and #585)
+// =============================================================================
+//
+// The stored settings, the PUT body, the GET/PUT response and the test-send
+// result. The API slice (`@marinoscar/platform-api/email`) wraps each with
+// `createZodDto`; the web slice reads the inferred types.
+//
+// NO SECRET IS STORED IN THE SETTINGS. The SMTP password and the SES secret
+// access key live in the encrypted credential store; the PUT body accepts
+// them write-only, and the response describes them only as a masked status.
+// Compile-time proofs at the bottom of this file fail the build the moment a
+// secret-named field is added to the stored settings or to the response.
+// =============================================================================
+import { z } from 'zod';
+import { pluggableDescriptorSchema } from '../settings/index.js';
+import { EMAIL_TRANSPORT_ID_PATTERN } from './constants.js';
+/**
+ * An email transport id: any string matching {@link EMAIL_TRANSPORT_ID_PATTERN}.
+ * Not an enum: an app registers transports (`registerEmailTransport`), and the
+ * API validates the id against the registry.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export const emailTransportIdSchema = z.string().regex(EMAIL_TRANSPORT_ID_PATTERN);
+/**
+ * One transport's non-secret settings as stored: whatever that transport's
+ * `settingsSchema` declares. The contract cannot see the registry, so it
+ * checks the shape (a record) and the API validates each entry with the
+ * transport that owns it.
+ *
+ * @stability experimental
+ */
+export const emailTransportSettingsSchema = z.record(z.string(), z.unknown());
+/**
+ * The `transports` record: transport id to that transport's settings.
+ *
+ * @stability experimental
+ */
+export const emailTransportsSchema = z.record(emailTransportIdSchema, emailTransportSettingsSchema);
+/**
+ * The `transports` record of a PUT: `null` removes a transport's stored
+ * settings (back to its defaults), an object is merged over them.
+ *
+ * @stability experimental
+ */
+export const emailTransportsPatchSchema = z.record(emailTransportIdSchema, emailTransportSettingsSchema.nullable());
+// The transport, as the settings and the test-send result carry it.
+const providerKindSchema = emailTransportIdSchema;
+/**
+ * The admin-configurable half of email delivery: which transport, where it
+ * lives, who the mail claims to be from. Ordinary configuration, safe to
+ * return from an admin endpoint; stored in the `email` row of
+ * `system_settings`.
+ *
+ * @stability stable
+ */
+export const emailSettingsSchema = z.object({
+    /**
+     * The id of the active transport: a built-in (`ses`, `smtp`) or one an app
+     * registered. `null` means "no transport chosen", the state of
+     * every fresh installation: a real, persisted state rather than an absent
+     * key.
+     */
+    provider: providerKindSchema.nullable(),
+    /** Master switch. Nothing is sent while this is false. */
+    enabled: z.boolean(),
+    /**
+     * Every transport's own non-secret settings, keyed by transport id
+     * (`transports.smtp.host`, `transports.my-relay.apiBase`), each validated by
+     * the transport that owns it. A row written before transports were pluggable
+     * has none: the API folds the flat fields below into `transports.ses` and
+     * `transports.smtp` when it reads such a row.
+     */
+    transports: emailTransportsSchema.optional(),
+    /**
+     * @deprecated Read view of `transports.ses.region`. SES region override. Absent means "use the deployment's SES region
+     * fallback" (`SES_REGION` in the reference app). A verified sending identity
+     * is regional, so the override is the usual case.
+     */
+    sesRegion: z.string().trim().min(1).optional(),
+    /**
+     * @deprecated Read view of `transports.ses.accessKeyId`. SES access key id. An IDENTIFIER, NOT A SECRET: it travels in clear in
+     * every SigV4 request. The secret access key lives in the credential store.
+     */
+    sesAccessKeyId: z.string().trim().min(1).optional(),
+    /** @deprecated Read view of `transports.smtp.host`. SMTP server host. */
+    smtpHost: z.string().trim().min(1).optional(),
+    /**
+     * @deprecated Read view of `transports.smtp.port`. SMTP port, validated here so a typo fails on the settings form rather than
+     * as a socket-level error.
+     */
+    smtpPort: z.number().int().min(1).max(65535).optional(),
+    /**
+     * @deprecated Read view of `transports.smtp.useTls`. Require TLS. Absent is treated as `true` by the provider: a mail
+     * credential must not cross the network in the clear because a checkbox was
+     * missing from a stored row.
+     */
+    smtpUseTls: z.boolean().optional(),
+    /**
+     * @deprecated Read view of `transports.smtp.username`. SMTP username. Absent means unauthenticated submission (an internal relay
+     * that authorises by source IP).
+     */
+    smtpUsername: z.string().trim().min(1).optional(),
+    /** Envelope and header sender, validated as an address. */
+    fromAddress: z.email().optional(),
+    /** Display name paired with `fromAddress`, e.g. `Acme <no-reply@acme.com>`. */
+    fromName: z.string().trim().min(1).max(100).optional(),
+});
+/**
+ * What a system with no email configuration reads as: no transport, switched
+ * off.
+ *
+ * @stability stable
+ */
+export const DEFAULT_EMAIL_SETTINGS = {
+    provider: null,
+    enabled: false,
+};
+/**
+ * What the admin page knows about a stored secret (the SMTP password, the SES
+ * secret access key) without being told the secret: whether it is set, the
+ * store's mask, and when and by whom it was last written.
+ *
+ * @stability stable
+ */
+export const credentialStatusSchema = z.object({
+    /** Is a secret stored at this credential's address? */
+    configured: z.boolean(),
+    /** The store's non-secret mask, e.g. `••••x9fQ`; null when nothing is stored. */
+    hint: z.string().nullable(),
+    /** When the stored secret was last written; null when nothing is stored. */
+    updatedAt: z.iso.datetime().nullable(),
+    /** Who last wrote it; null when nothing is stored, or the user was deleted. */
+    updatedByUserId: z.uuid().nullable(),
+});
+/**
+ * The `GET` and `PUT /api/email-settings` response body (inside the global
+ * `{ data }` envelope): the settings, a descriptor per registered transport,
+ * the masked status of every transport secret, why
+ * the stored row could not be read (field paths only; the read degrades to
+ * the defaults instead of failing, so the page that repairs the row still
+ * renders), and the row's version for `If-Match`.
+ *
+ * @stability stable
+ */
+export const emailSettingsResponseSchema = emailSettingsSchema.extend({
+    /** Every REGISTERED transport's own settings, keyed by transport id, with its defaults filled. */
+    transports: emailTransportsSchema,
+    /**
+     * One descriptor per registered transport, in registration order: its id
+     * and label, its non-secret settings fields and one `secret` field per
+     * declared secret carrying only whether a value is stored (`hasValue`),
+     * never the value. The admin page renders any transport without
+     * hard-coded knowledge of it.
+     */
+    descriptors: z.array(pluggableDescriptorSchema),
+    /**
+     * The masked status of every declared secret of every registered transport:
+     * `{ <transportId>: { <secretName>: status } }`. Nothing here can carry a value.
+     */
+    secretStatuses: z.record(emailTransportIdSchema, z.record(z.string(), credentialStatusSchema)),
+    /** @deprecated `secretStatuses.smtp.password`. The SMTP password's masked status. */
+    smtpPasswordStatus: credentialStatusSchema,
+    /** @deprecated `secretStatuses.ses.secretAccessKey`. The SES secret access key's masked status. */
+    sesSecretAccessKeyStatus: credentialStatusSchema,
+    /** Why the stored configuration could not be read; null normally. Field paths only. */
+    settingsError: z.string().nullable(),
+    /** Bumped on every write; pass back as `If-Match` on PUT. `0` while nothing is stored. */
+    version: z.number().int(),
+    /** When the row last changed. */
+    updatedAt: z.iso.datetime().nullable(),
+    /** Who last changed it. */
+    updatedBy: z
+        .object({
+        /** The user's id. */
+        id: z.uuid(),
+        /** The user's address. */
+        email: z.email(),
+    })
+        .nullable(),
+});
+/**
+ * Length ceiling on a submitted secret. Not a security control: a bound on
+ * what a paste accident can push into an encrypted column.
+ */
+const MAX_SECRET_LENGTH = 1024;
+/**
+ * A settings field an admin left empty: a cleared input submits `''`, a reset
+ * controlled field `null`. A union rather than a `z.preprocess`, because the
+ * OpenAPI generator cannot represent a transform. The service converts both
+ * to "absent".
+ */
+const unset = z.union([z.literal(''), z.null()]);
+/** The stored rule for one field, plus the two "empty box" forms. */
+function blankable(inner) {
+    return z.union([unset, inner]);
+}
+/**
+ * The `PUT /api/email-settings` body: every settings field (blankable), the
+ * `transports` patch, plus the WRITE-ONLY secrets (`secrets`, and the two
+ * legacy aliases). A blank secret (absent, `null` or `''`)
+ * preserves the stored one; erasing a stored secret is not expressible here.
+ *
+ * @stability stable
+ */
+export const updateEmailSettingsSchema = emailSettingsSchema.extend({
+    /**
+     * Transport settings to merge, per transport id, each validated by the
+     * transport that owns it. `null` removes a transport's stored settings (back
+     * to its defaults); a setting a transport's entry omits keeps its stored
+     * value. `transports.<id>` wins over a legacy flat field for the same setting.
+     */
+    transports: emailTransportsPatchSchema.optional(),
+    /** @deprecated Alias of `transports.ses.region`; blank clears it. */
+    sesRegion: blankable(emailSettingsSchema.shape.sesRegion),
+    /** @deprecated Alias of `transports.ses.accessKeyId` (not a secret); blank clears it. */
+    sesAccessKeyId: blankable(emailSettingsSchema.shape.sesAccessKeyId),
+    /** @deprecated Alias of `transports.smtp.host`; blank clears it. */
+    smtpHost: blankable(emailSettingsSchema.shape.smtpHost),
+    /** @deprecated Alias of `transports.smtp.port`; blank clears it (587 applies). */
+    smtpPort: blankable(emailSettingsSchema.shape.smtpPort),
+    /** @deprecated Alias of `transports.smtp.useTls`; blank clears it (on applies). */
+    smtpUseTls: blankable(emailSettingsSchema.shape.smtpUseTls),
+    /** @deprecated Alias of `transports.smtp.username`; blank means unauthenticated submission. */
+    smtpUsername: blankable(emailSettingsSchema.shape.smtpUsername),
+    /** Sender address; blank clears it. */
+    fromAddress: blankable(emailSettingsSchema.shape.fromAddress),
+    /** Sender display name; blank clears it. */
+    fromName: blankable(emailSettingsSchema.shape.fromName),
+    /** The SMTP password. Write-only; blank preserves the stored one. Alias of `secrets.smtp.password`. */
+    smtpPassword: z.string().max(MAX_SECRET_LENGTH).nullish(),
+    /** The SES secret access key. Write-only; blank preserves the stored one. Alias of `secrets.ses.secretAccessKey`. */
+    sesSecretAccessKey: z.string().max(MAX_SECRET_LENGTH).nullish(),
+    /**
+     * WRITE-ONLY secrets of any transport: `{ <transportId>: { <secretName>: value } }`,
+     * the names the transport declares (`descriptors[].fields` of kind `secret`).
+     * A blank value keeps the stored one. Never echoed back.
+     */
+    secrets: z.record(emailTransportIdSchema, z.record(z.string(), z.string().max(4096).nullish())).optional(),
+});
+/**
+ * The `POST /api/email-settings/test` response body. HTTP 200 even when the
+ * send failed: read `success`, and show `error`, the provider's own message
+ * (already redacted of every credential and length-capped by the API).
+ *
+ * @stability stable
+ */
+export const testEmailResultSchema = z.object({
+    /** Did the provider ACCEPT the message (not: was it delivered)? */
+    success: z.boolean(),
+    /** Where it went: always the caller's own address (there is no recipient parameter). */
+    sentTo: z.email(),
+    /** Which transport carried (or refused) it; null when none was configured. */
+    providerKind: providerKindSchema.nullable(),
+    /** The transport's message id, on success. */
+    messageId: z.string().nullable(),
+    /** The provider's error, verbatim after redaction; null on success. */
+    error: z.string().nullable(),
+    /** When the attempt was made (ISO 8601). */
+    attemptedAt: z.iso.datetime(),
+});
+/**
+ * The proof that {@link EmailSettings} carries no secret (fails to compile otherwise).
+ *
+ * @stability stable
+ */
+export const EMAIL_SETTINGS_CARRIES_NO_SECRET = true;
+/**
+ * The proof that {@link EmailSettingsResponse} carries no secret (fails to compile otherwise).
+ *
+ * @stability stable
+ */
+export const EMAIL_SETTINGS_RESPONSE_CARRIES_NO_SECRET = true;
+//# sourceMappingURL=schemas.js.map

package/dist/esm/email/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/email/schemas.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,yEAAyE;AACzE,mCAAmC;AACnC,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,0DAA0D;AAC1D,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,6EAA6E;AAC7E,yEAAyE;AACzE,gFAAgF;AAEhF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAW5D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,sBAAsB,EAAE,4BAA4B,CAAC,CAAC;AAEpG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,sBAAsB,EAAE,4BAA4B,CAAC,QAAQ,EAAE,CAAC,CAAC;AAEpH,oEAAoE;AACpE,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IAEvC,0DAA0D;IAC1D,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IAEpB;;;;;;OAMG;IACH,UAAU,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAE5C;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAE9C;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEnD,yEAAyE;IACzE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAE7C;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE;IAEvD;;;;OAIG;IACH,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAElC;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEjD,2DAA2D;IAC3D,WAAW,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE;IAEjC,+EAA+E;IAC/E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AASH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,KAAK;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,uDAAuD;IACvD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;IACvB,iFAAiF;IACjF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,4EAA4E;IAC5E,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtC,+EAA+E;IAC/E,eAAe,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AASH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,MAAM,CAAC;IACpE,kGAAkG;IAClG,UAAU,EAAE,qBAAqB;IACjC;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;IAC/C;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,sBAAsB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,sBAAsB,CAAC,CAAC;IAC9F,qFAAqF;IACrF,kBAAkB,EAAE,sBAAsB;IAC1C,mGAAmG;IACnG,wBAAwB,EAAE,sBAAsB;IAChD,uFAAuF;IACvF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,0FAA0F;IAC1F,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,iCAAiC;IACjC,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtC,2BAA2B;IAC3B,SAAS,EAAE,CAAC;SACT,MAAM,CAAC;QACN,qBAAqB;QACrB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;QACZ,0BAA0B;QAC1B,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE;KACjB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AASH;;;GAGG;AACH,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAEjD,qEAAqE;AACrE,SAAS,SAAS,CAAyB,KAAQ;IACjD,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,mBAAmB,CAAC,MAAM,CAAC;IAClE;;;;;OAKG;IACH,UAAU,EAAE,0BAA0B,CAAC,QAAQ,EAAE;IACjD,qEAAqE;IACrE,SAAS,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC;IACzD,yFAAyF;IACzF,cAAc,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,cAAc,CAAC;IACnE,oEAAoE;IACpE,QAAQ,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;IACvD,kFAAkF;IAClF,QAAQ,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;IACvD,mFAAmF;IACnF,UAAU,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC;IAC3D,+FAA+F;IAC/F,YAAY,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,YAAY,CAAC;IAC/D,uCAAuC;IACvC,WAAW,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;IAC7D,4CAA4C;IAC5C,QAAQ,EAAE,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;IACvD,uGAAuG;IACvG,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE;IACzD,qHAAqH;IACrH,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE;IAC/D;;;;OAIG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,sBAAsB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC3G,CAAC,CAAC;AASH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,mEAAmE;IACnE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,wFAAwF;IACxF,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE;IACjB,8EAA8E;IAC9E,YAAY,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IAC3C,8CAA8C;IAC9C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,uEAAuE;IACvE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,4CAA4C;IAC5C,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAyCH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAiC,IAAI,CAAC;AAUnF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAAyC,IAAI,CAAC"}