firstly 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # firstly
 
+## 0.4.2
+
+### Patch Changes
+
+- [#258](https://github.com/jycouet/firstly/pull/258) [`43f3f77`](https://github.com/jycouet/firstly/commit/43f3f77aa34f064720c90cdd240ac050a360ecf6) Thanks [@jycouet](https://github.com/jycouet)! - `firstly/changeLog`: export the `ChangeLog` entity class so apps can declare `@Relations` to it (e.g. linking changelog rows back to a `User`).
+
+- [#253](https://github.com/jycouet/firstly/pull/253) [`6e203da`](https://github.com/jycouet/firstly/commit/6e203dab7bcbfe043c087703e8c199d42916015f) Thanks [@jycouet](https://github.com/jycouet)! - `firstly/mail`: export `MailSection`, persist nodemailer response into `Mail.metadata.transport` (so provider IDs like Resend's `re_...` are recoverable from the DB), ship drop-in `<WriteMail />` + `<LastMails />` admin components and an opt-in `MailController.sendTest` BackendMethod (`mail({ enableTest: true })`), plus a Resend docs section. Root: new `errorMessage(err)` helper that handles native `Error`, remult `ErrorInfo` rejections, and falls back to JSON instead of `[object Object]`.
+
+- [#252](https://github.com/jycouet/firstly/pull/252) [`a4ee628`](https://github.com/jycouet/firstly/commit/a4ee628262ac290901039eba77cdf508dde48a2e) Thanks [@jycouet](https://github.com/jycouet)! - `firstly/sqlAdmin`: drop daisyUI dep, style with raw Tailwind, and add docs page.
+
+## 0.4.1
+
+### Patch Changes
+
+- [#250](https://github.com/jycouet/firstly/pull/250) [`53916ad`](https://github.com/jycouet/firstly/commit/53916ad519835a47e3598afb68ce6d84356af944) Thanks [@jycouet](https://github.com/jycouet)! - Add `firstly/sqlAdmin` module: a drop-in `<SqlAdmin />` Svelte component plus a `BackendMethod` controller gated by `Roles_SqlAdmin.SqlAdmin_Admin` (or `FF_Role.FF_Role_Admin`). The component ships with prefilled queries (DB size, table sizes, indexes) and logs results as `for AI: <rows>` to the browser console for chrome-devtools / AI-agent inspection. `sqlAdmin({ path })` logs an AI hint on server start pointing to the page (default `/sql/admin`).
+
+  Add `FF_Allow` and `FF_Filter` helpers (exported from `firstly`) for owner-only / admin-or-owner row checks and prefilters - usable in `allowApi*` and `apiPrefilter`. Both accept an entity generic (`FF_Allow.owner<Task>('userId')`) for type-safe column names; `col` defaults to `'userId'` if omitted. The `ownerOr<T>({ col?, roles })` variants are shortcuts for the "admin (or any role) OR owner" pattern.
+
 ## 0.4.0
 
 ### Minor Changes

package/esm/changeLog/index.d.ts

@@ -1,6 +1,6 @@
 import { type EntityOptions, type FieldRef, type FieldsRef, type LifecycleEvent } from 'remult';
-import { Roles_ChangeLog, type change } from './changeLogEntities';
-export { Roles_ChangeLog };
+import { ChangeLog, Roles_ChangeLog, type change } from './changeLogEntities';
+export { ChangeLog, Roles_ChangeLog };
 export type { change };
 export interface changeEvent {
     date: Date;

package/esm/changeLog/index.js

@@ -1,6 +1,6 @@
 import { getEntityRef, IdEntity, isBackend, remult, repo, } from 'remult';
 import { ChangeLog, Roles_ChangeLog } from './changeLogEntities';
-export { Roles_ChangeLog };
+export { ChangeLog, Roles_ChangeLog };
 export async function recordSaved(entity, e, options) {
     if (isBackend()) {
         const changes = [];

package/esm/core/FF_Allow.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Row-level allow helpers (for `allowApiUpdate`, `allowApiDelete`, ...).
+ *
+ * Pair with `FF_Filter` (the equivalent for `apiPrefilter`).
+ *
+ * Pass the entity type as a generic (`FF_Allow.owner<Task>('userId')`) to get
+ * autocompletion and type-safety on the column name. Without a generic the
+ * column is just a `string`.
+ */
+export declare const FF_Allow: {
+    /**
+     * Allow only when the row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Owner-only update / delete (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.owner<Task>('userId'), // typed: 'userId' must be a key of Task
+     *   allowApiDelete: FF_Allow.owner<Task>(),        // defaults to 'userId'
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin OR owner", prefer `FF_Allow.ownerOr` instead of inlining the
+     * combination yourself.
+     */
+    owner: <T>(col?: keyof T & string) => (entity?: T) => boolean;
+    /**
+     * Allow when the current user has any of the given `roles`, OR when the
+     * row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin OR owner (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.ownerOr<Task>({ roles: [Roles.Admin] }),
+     *   allowApiDelete: FF_Allow.ownerOr<Task>({ col: 'createdBy', roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: <T>({ col, roles }: {
+        col?: keyof T & string;
+        roles: string[];
+    }) => (entity?: T) => boolean;
+};

package/esm/core/FF_Allow.js

@@ -0,0 +1,54 @@
+import { remult } from 'remult';
+/**
+ * Row-level allow helpers (for `allowApiUpdate`, `allowApiDelete`, ...).
+ *
+ * Pair with `FF_Filter` (the equivalent for `apiPrefilter`).
+ *
+ * Pass the entity type as a generic (`FF_Allow.owner<Task>('userId')`) to get
+ * autocompletion and type-safety on the column name. Without a generic the
+ * column is just a `string`.
+ */
+export const FF_Allow = {
+    /**
+     * Allow only when the row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Owner-only update / delete (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.owner<Task>('userId'), // typed: 'userId' must be a key of Task
+     *   allowApiDelete: FF_Allow.owner<Task>(),        // defaults to 'userId'
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin OR owner", prefer `FF_Allow.ownerOr` instead of inlining the
+     * combination yourself.
+     */
+    owner: (col = 'userId') => (entity) => !!remult.user?.id && entity?.[col] === remult.user.id,
+    /**
+     * Allow when the current user has any of the given `roles`, OR when the
+     * row's `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin OR owner (typed):
+     * ```ts
+     * import { FF_Entity, FF_Allow } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   allowApiUpdate: FF_Allow.ownerOr<Task>({ roles: [Roles.Admin] }),
+     *   allowApiDelete: FF_Allow.ownerOr<Task>({ col: 'createdBy', roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: ({ col = 'userId', roles }) => (entity) => roles.some((r) => remult.isAllowed(r)) ||
+        (!!remult.user?.id && entity?.[col] === remult.user.id),
+};

package/esm/core/FF_Filter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ *
+ * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ *
+ * Pass the entity type as a generic (`FF_Filter.owner<Task>('userId')`) to get
+ * autocompletion and type-safety on the column name. Without a generic the
+ * column is just a `string`.
+ */
+export declare const FF_Filter: {
+    /**
+     * Prefilter rows where `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted. When anonymous, yields
+     * `IN (NULL)` which matches nothing.
+     *
+     * @example
+     * Owner-only prefilter (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.owner<Task>('userId'),
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin sees all, others see only their own", prefer
+     * `FF_Filter.ownerOr` instead of inlining the combination yourself.
+     */
+    owner: <T>(col?: keyof T & string) => any;
+    /**
+     * Prefilter that returns `{}` (no filter) when the current user has any of
+     * the given `roles`, otherwise restricts to rows where `col` equals the
+     * current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin sees all, others only their own (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.ownerOr<Task>({ roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: <T>({ col, roles, }: {
+        col?: keyof T & string;
+        roles: string[];
+    }) => any;
+};

package/esm/core/FF_Filter.js

@@ -0,0 +1,57 @@
+import { remult } from 'remult';
+/**
+ * Prefilter helpers (for `apiPrefilter`, `backendPrefilter`).
+ *
+ * Pair with `FF_Allow` (the equivalent for `allowApi*` row checks).
+ *
+ * Pass the entity type as a generic (`FF_Filter.owner<Task>('userId')`) to get
+ * autocompletion and type-safety on the column name. Without a generic the
+ * column is just a `string`.
+ */
+export const FF_Filter = {
+    /**
+     * Prefilter rows where `col` equals the current user id.
+     *
+     * `col` defaults to `'userId'` if omitted. When anonymous, yields
+     * `IN (NULL)` which matches nothing.
+     *
+     * @example
+     * Owner-only prefilter (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.owner<Task>('userId'),
+     * })
+     * export class Task { ... }
+     * ```
+     *
+     * For "admin sees all, others see only their own", prefer
+     * `FF_Filter.ownerOr` instead of inlining the combination yourself.
+     */
+    owner: (col = 'userId') => ({ [col]: [remult.user?.id] }),
+    /**
+     * Prefilter that returns `{}` (no filter) when the current user has any of
+     * the given `roles`, otherwise restricts to rows where `col` equals the
+     * current user id.
+     *
+     * `col` defaults to `'userId'` if omitted.
+     *
+     * @example
+     * Admin sees all, others only their own (typed):
+     * ```ts
+     * import { FF_Entity, FF_Filter } from '..'
+     * import { Roles } from '../roles'
+     *
+     * \@FF_Entity<Task>('tasks', {
+     *   apiPrefilter: () => FF_Filter.ownerOr<Task>({ roles: [Roles.Admin] }),
+     * })
+     * export class Task { ... }
+     * ```
+     */
+    ownerOr: ({ col = 'userId', roles, }) => {
+        if (roles.some((r) => remult.isAllowed(r)))
+            return {};
+        return { [col]: [remult.user?.id] };
+    },
+};

package/esm/core/FF_Validators.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A localized message. Either a literal string (single-locale projects) or a
+ * function called at validation time (multi-locale projects - typically a
+ * paraglide / i18next / lingui message function that resolves against the
+ * current request's locale).
+ */
+export type LocalizedMessage = string | (() => string);
+export type EmailMessages = {
+    /** Returned when the value doesn't match the basic email shape regex. */
+    invalid?: LocalizedMessage;
+    /** Returned when the domain is malformed (`..`, leading/trailing dot, missing TLD). */
+    invalidDomain?: LocalizedMessage;
+    /** Returned when the domain is on the blocked list (`example.com`, `test.com`, ...). */
+    blockedDomain?: LocalizedMessage;
+    /** Returned when the TLD is on the blocked list (`.test`, `.example`, `.invalid`, ...). */
+    blockedTld?: LocalizedMessage;
+};
+export type ValidatorMessages = {
+    email?: EmailMessages;
+};
+/**
+ * Build a project-localized set of validators. Override any subset of
+ * messages; defaults are English.
+ *
+ * Each message can be a literal string OR a function returning a string.
+ * Function form is called at validation time (NOT at factory call time), so
+ * pass paraglide / i18next / lingui message functions to get per-request
+ * locale resolution:
+ *
+ * ```ts
+ * import { createValidators } from '..'
+ * import * as m from '../paraglide/messages'
+ *
+ * export const App_Validators = createValidators({
+ *   email: {
+ *     invalid:        () => m.email_invalid(),
+ *     invalidDomain:  () => m.email_invalid_domain(),
+ *     blockedDomain:  () => m.email_blocked_domain(),
+ *     blockedTld:     () => m.email_blocked_tld(),
+ *   },
+ * })
+ * ```
+ *
+ * Each validator group exposes two members:
+ * - `checkXxx(value)` - pure function, returns `true` on valid or a
+ *   localized error message string. Use for live UI feedback.
+ * - `xxx` - a Remult `Validator` wrapping the same `checkXxx`. Use as
+ *   `@Fields.string({ validate: app.email })`.
+ */
+export declare function createValidators(messages?: ValidatorMessages): {
+    checkEmail: (value: string) => true | string;
+    email: import("remult").Validator<string>;
+};
+/**
+ * Default English validators. For localized messages, build your own with
+ * `createValidators(messages)` and import that one in your project instead.
+ */
+export declare const FF_Validators: {
+    checkEmail: (value: string) => true | string;
+    email: import("remult").Validator<string>;
+};
+/** Convenience direct export of `FF_Validators.checkEmail` for ad-hoc use. */
+export declare const checkEmail: (value: string) => true | string;

package/esm/core/FF_Validators.js

@@ -0,0 +1,97 @@
+import { createValueValidator } from 'remult';
+// RFC 2606 reserved test/example domains and obvious placeholders.
+const BLOCKED_EMAIL_DOMAINS = new Set([
+    'example.com',
+    'example.net',
+    'example.org',
+    'test.com',
+    'test.net',
+    'test.org',
+    'foo.com',
+    'foo.bar',
+    'bar.com',
+    'baz.com',
+    'domain.com',
+    'mail.com',
+    'localhost',
+    'invalid',
+]);
+const BLOCKED_EMAIL_TLDS = new Set(['test', 'example', 'invalid', 'localhost', 'local']);
+const EMAIL_SHAPE_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const DEFAULT_EMAIL_MESSAGES = {
+    invalid: 'Invalid email',
+    invalidDomain: 'Invalid domain',
+    blockedDomain: 'Test/example email not accepted',
+    blockedTld: 'Test/example TLD not accepted',
+};
+/** Resolve a `LocalizedMessage` to its current string value. */
+function resolve(m) {
+    return typeof m === 'function' ? m() : m;
+}
+/**
+ * Build a project-localized set of validators. Override any subset of
+ * messages; defaults are English.
+ *
+ * Each message can be a literal string OR a function returning a string.
+ * Function form is called at validation time (NOT at factory call time), so
+ * pass paraglide / i18next / lingui message functions to get per-request
+ * locale resolution:
+ *
+ * ```ts
+ * import { createValidators } from '..'
+ * import * as m from '../paraglide/messages'
+ *
+ * export const App_Validators = createValidators({
+ *   email: {
+ *     invalid:        () => m.email_invalid(),
+ *     invalidDomain:  () => m.email_invalid_domain(),
+ *     blockedDomain:  () => m.email_blocked_domain(),
+ *     blockedTld:     () => m.email_blocked_tld(),
+ *   },
+ * })
+ * ```
+ *
+ * Each validator group exposes two members:
+ * - `checkXxx(value)` - pure function, returns `true` on valid or a
+ *   localized error message string. Use for live UI feedback.
+ * - `xxx` - a Remult `Validator` wrapping the same `checkXxx`. Use as
+ *   `@Fields.string({ validate: app.email })`.
+ */
+export function createValidators(messages = {}) {
+    const m = {
+        ...DEFAULT_EMAIL_MESSAGES,
+        ...messages.email,
+    };
+    function checkEmail(value) {
+        if (value === '')
+            return true;
+        if (!EMAIL_SHAPE_RE.test(value))
+            return resolve(m.invalid);
+        const at = value.lastIndexOf('@');
+        const domain = value.slice(at + 1).toLowerCase();
+        if (!domain || domain.includes('..') || domain.startsWith('.') || domain.endsWith('.')) {
+            return resolve(m.invalidDomain);
+        }
+        if (BLOCKED_EMAIL_DOMAINS.has(domain))
+            return resolve(m.blockedDomain);
+        const tld = domain.split('.').pop() ?? '';
+        if (BLOCKED_EMAIL_TLDS.has(tld))
+            return resolve(m.blockedTld);
+        if (!domain.includes('.') || tld.length < 2)
+            return resolve(m.invalidDomain);
+        return true;
+    }
+    return {
+        checkEmail,
+        // Pass a function so the per-request locale is resolved when the
+        // validator actually fires, not when the validator is built.
+        email: createValueValidator(checkEmail, () => resolve(m.invalid)),
+    };
+}
+/**
+ * Default English validators. For localized messages, build your own with
+ * `createValidators(messages)` and import that one in your project instead.
+ */
+export const FF_Validators = createValidators();
+/** Convenience direct export of `FF_Validators.checkEmail` for ad-hoc use. */
+export const checkEmail = FF_Validators.checkEmail;

package/esm/core/helper.d.ts

@@ -1,2 +1,19 @@
 import type { ErrorInfo } from 'remult';
 export declare function isError<T>(object: any): object is ErrorInfo<T>;
+/**
+ * Extract a user-readable message from any thrown / rejected value.
+ *
+ * Why a helper instead of `String(err)`: when a remult `BackendMethod`
+ * rejects, the client receives a plain object matching `ErrorInfo`
+ * (`{ message?, modelState? }`) - **not** an `Error` instance. The naive
+ * `err instanceof Error ? err.message : String(err)` fallback prints
+ * `[object Object]` for those rejections and surfaces nothing useful.
+ *
+ * Order of resolution:
+ * 1. plain string -> as-is
+ * 2. native `Error` (incl. `EntityError`, `ForbiddenError`) -> `.message`
+ * 3. `ErrorInfo`-shaped object with `.message` -> that message
+ * 4. `ErrorInfo`-shaped object with `.modelState` -> first non-empty value
+ * 5. fallback to `JSON.stringify(err)` (so the shape is at least readable)
+ */
+export declare function errorMessage(err: unknown, fallback?: string): string;

package/esm/core/helper.js

@@ -1,3 +1,43 @@
 export function isError(object) {
     return object;
 }
+/**
+ * Extract a user-readable message from any thrown / rejected value.
+ *
+ * Why a helper instead of `String(err)`: when a remult `BackendMethod`
+ * rejects, the client receives a plain object matching `ErrorInfo`
+ * (`{ message?, modelState? }`) - **not** an `Error` instance. The naive
+ * `err instanceof Error ? err.message : String(err)` fallback prints
+ * `[object Object]` for those rejections and surfaces nothing useful.
+ *
+ * Order of resolution:
+ * 1. plain string -> as-is
+ * 2. native `Error` (incl. `EntityError`, `ForbiddenError`) -> `.message`
+ * 3. `ErrorInfo`-shaped object with `.message` -> that message
+ * 4. `ErrorInfo`-shaped object with `.modelState` -> first non-empty value
+ * 5. fallback to `JSON.stringify(err)` (so the shape is at least readable)
+ */
+export function errorMessage(err, fallback = 'Unknown error') {
+    if (err == null)
+        return fallback;
+    if (typeof err === 'string')
+        return err || fallback;
+    if (err instanceof Error && err.message)
+        return err.message;
+    if (typeof err === 'object') {
+        const e = err;
+        if (typeof e.message === 'string' && e.message)
+            return e.message;
+        if (e.modelState && typeof e.modelState === 'object') {
+            const first = Object.values(e.modelState).find((v) => typeof v === 'string' && v);
+            if (typeof first === 'string')
+                return first;
+        }
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}

package/esm/index.d.ts

@@ -7,7 +7,11 @@ export { BaseEnum } from './core/BaseEnum.js';
 export type { BaseEnumOptions, BaseItem, BaseItemLight, FF_Icon } from './core/BaseEnum.js';
 export { FF_Entity } from './core/FF_Entity.js';
 export { FF_Role } from './core/common.js';
-export { isError } from './core/helper.js';
+export { FF_Allow } from './core/FF_Allow.js';
+export { FF_Filter } from './core/FF_Filter.js';
+export { FF_Validators, createValidators } from './core/FF_Validators.js';
+export type { EmailMessages, ValidatorMessages } from './core/FF_Validators.js';
+export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export type { ResolvedType, UnArray, RecursivePartial } from './core/types.js';
 export { tw } from './core/tailwind.js';

package/esm/index.js

@@ -9,7 +9,10 @@ export const ff_Log = new h.Log('firstly');
 export { BaseEnum } from './core/BaseEnum.js';
 export { FF_Entity } from './core/FF_Entity.js';
 export { FF_Role } from './core/common.js';
-export { isError } from './core/helper.js';
+export { FF_Allow } from './core/FF_Allow.js';
+export { FF_Filter } from './core/FF_Filter.js';
+export { FF_Validators, createValidators } from './core/FF_Validators.js';
+export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export { tw } from './core/tailwind.js';
 // Misc primitives still exposed from the root.

package/esm/mail/MailController.d.ts

@@ -0,0 +1,22 @@
+export declare class MailController {
+    /**
+     * Drives the bundled `<WriteMail />` component. Sends a single-section
+     * mail through `remult.context.sendMail` (set by the `mail()` module) and
+     * returns the provider's `messageId` when available.
+     *
+     * Each of `to`, `cc`, `bcc` is a comma-separated string. Splitting,
+     * trimming, lowercasing, and per-entry validation happen here on the
+     * server - the client just hands over what the user typed.
+     */
+    static sendTest(input: {
+        to: string;
+        cc?: string;
+        bcc?: string;
+        subject: string;
+        body: string;
+    }): Promise<{
+        ok: boolean;
+        messageId: string | null;
+        error: string | null;
+    }>;
+}

package/esm/mail/MailController.js

@@ -0,0 +1,68 @@
+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;
+};
+import { BackendMethod, remult } from 'remult';
+import { checkEmail } from '../core/FF_Validators';
+import { Roles_Mail } from './Roles_Mail';
+/** Split on commas, trim, lowercase, drop empties. */
+function parseRecipients(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
+export class MailController {
+    /**
+     * Drives the bundled `<WriteMail />` component. Sends a single-section
+     * mail through `remult.context.sendMail` (set by the `mail()` module) and
+     * returns the provider's `messageId` when available.
+     *
+     * Each of `to`, `cc`, `bcc` is a comma-separated string. Splitting,
+     * trimming, lowercasing, and per-entry validation happen here on the
+     * server - the client just hands over what the user typed.
+     */
+    static async sendTest(input) {
+        if (import.meta.env.SSR) {
+            if (!remult.context.sendMail) {
+                throw new Error('mail module not registered (call mail() in remultApi.modules)');
+            }
+            const tos = parseRecipients(input.to);
+            const ccs = parseRecipients(input.cc);
+            const bccs = parseRecipients(input.bcc);
+            if (tos.length === 0 && ccs.length === 0 && bccs.length === 0) {
+                throw new Error('At least one recipient is required (to, cc, or bcc).');
+            }
+            for (const entry of [...tos, ...ccs, ...bccs]) {
+                const verdict = checkEmail(entry);
+                if (verdict !== true)
+                    throw new Error(`${verdict}: "${entry}"`);
+            }
+            const safe = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
+            const r = await remult.context.sendMail('test', {
+                to: tos.length === 1 ? tos[0] : tos,
+                cc: ccs.length ? (ccs.length === 1 ? ccs[0] : ccs) : undefined,
+                bcc: bccs.length ? (bccs.length === 1 ? bccs[0] : bccs) : undefined,
+                subject: input.subject,
+                sections: [
+                    {
+                        html: `<p style="margin:0;white-space:pre-wrap;">${safe(input.body) || '<em>(no body)</em>'}</p>`,
+                    },
+                ],
+            });
+            return {
+                ok: !!r.data,
+                messageId: r.data?.messageId ?? null,
+                error: r.error ? String(r.error.message ?? r.error) : null,
+            };
+        }
+        throw new Error('sendTest: server-only');
+    }
+}
+__decorate([
+    BackendMethod({ allowed: Roles_Mail.Mail_Admin })
+], MailController, "sendTest", null);

package/esm/mail/index.d.ts

@@ -1,6 +1,11 @@
 import { Log } from '@kitql/helpers';
 import { Mail } from './Mail';
+export { Mail } from './Mail';
+export { MailController } from './MailController';
 export { Roles_Mail } from './Roles_Mail';
+export type { MailSection } from './types';
+export { default as WriteMail } from './ui/WriteMail.svelte';
+export { default as LastMails } from './ui/LastMails.svelte';
 export declare const key = "mail";
 export declare const log: Log;
 export declare const mailEntities: {

package/esm/mail/index.js

@@ -1,6 +1,10 @@
 import { Log } from '@kitql/helpers';
 import { Mail } from './Mail';
+export { Mail } from './Mail';
+export { MailController } from './MailController';
 export { Roles_Mail } from './Roles_Mail';
+export { default as WriteMail } from './ui/WriteMail.svelte';
+export { default as LastMails } from './ui/LastMails.svelte';
 export const key = 'mail';
 export const log = new Log(key);
 export const mailEntities = {

package/esm/mail/server/formatMailHelper.d.ts

@@ -1,16 +1,11 @@
+import type { MailSection } from '../types';
 export type MailStyle = {
     service: string;
     primaryColor: string;
     secondaryColor: string;
     subject: string;
     title: string;
-    sections: {
-        html: string;
-        cta?: {
-            html: string;
-            link: string;
-        } | undefined;
-    }[];
+    sections: MailSection[];
     footer: string;
 };
 export declare const toHtml: (args: MailStyle) => string;