@beechcms/api 0.6.0-preview.2 → 0.6.0-preview.3

package/dist/features/automations/automations.schema.d.ts

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+import type { WhenNode } from '@beechcms/core';
+export declare const automationActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"set_variable">;
+    name: z.ZodString;
+    seed_slug: z.ZodOptional<z.ZodString>;
+    fixed_id: z.ZodOptional<z.ZodString>;
+    column: z.ZodOptional<z.ZodString>;
+    filters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            lt: "lt";
+            contains: "contains";
+            neq: "neq";
+            isempty: "isempty";
+            isnotempty: "isnotempty";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    order_by: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    load_type: z.ZodOptional<z.ZodEnum<{
+        fruit: "fruit";
+        branch: "branch";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"webhook">;
+    url: z.ZodString;
+    method: z.ZodOptional<z.ZodEnum<{
+        POST: "POST";
+        PUT: "PUT";
+        GET: "GET";
+    }>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body_template: z.ZodPreprocess<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"send_mail">;
+    to: z.ZodString;
+    subject_template: z.ZodString;
+    body_template: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"edit_field">;
+    field: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"create_entry">;
+    seed_slug: z.ZodString;
+    field_map: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>], "type">;
+export declare const createAutomationSchema: z.ZodObject<{
+    seed_slug: z.ZodString;
+    name: z.ZodString;
+    triggers: z.ZodArray<z.ZodObject<{
+        event: z.ZodEnum<{
+            create: "create";
+            update: "update";
+            delete: "delete";
+            cron: "cron";
+        }>;
+        cron: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    trigger_conditions: z.ZodOptional<z.ZodNullable<z.ZodType<WhenNode, unknown, z.core.$ZodTypeInternals<WhenNode, unknown>>>>;
+    actions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"set_variable">;
+        name: z.ZodString;
+        seed_slug: z.ZodOptional<z.ZodString>;
+        fixed_id: z.ZodOptional<z.ZodString>;
+        column: z.ZodOptional<z.ZodString>;
+        filters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
+                gt: "gt";
+                lt: "lt";
+                contains: "contains";
+                neq: "neq";
+                isempty: "isempty";
+                isnotempty: "isnotempty";
+            }>;
+            value: z.ZodUnknown;
+        }, z.core.$strip>>>;
+        order_by: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+        load_type: z.ZodOptional<z.ZodEnum<{
+            fruit: "fruit";
+            branch: "branch";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"webhook">;
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodEnum<{
+            POST: "POST";
+            PUT: "PUT";
+            GET: "GET";
+        }>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body_template: z.ZodPreprocess<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"send_mail">;
+        to: z.ZodString;
+        subject_template: z.ZodString;
+        body_template: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"edit_field">;
+        field: z.ZodString;
+        value: z.ZodUnknown;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"create_entry">;
+        seed_slug: z.ZodString;
+        field_map: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export declare const updateAutomationSchema: z.ZodObject<{
+    seed_slug: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        event: z.ZodEnum<{
+            create: "create";
+            update: "update";
+            delete: "delete";
+            cron: "cron";
+        }>;
+        cron: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    trigger_conditions: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodType<WhenNode, unknown, z.core.$ZodTypeInternals<WhenNode, unknown>>>>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"set_variable">;
+        name: z.ZodString;
+        seed_slug: z.ZodOptional<z.ZodString>;
+        fixed_id: z.ZodOptional<z.ZodString>;
+        column: z.ZodOptional<z.ZodString>;
+        filters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            op: z.ZodEnum<{
+                eq: "eq";
+                gt: "gt";
+                lt: "lt";
+                contains: "contains";
+                neq: "neq";
+                isempty: "isempty";
+                isnotempty: "isnotempty";
+            }>;
+            value: z.ZodUnknown;
+        }, z.core.$strip>>>;
+        order_by: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+        load_type: z.ZodOptional<z.ZodEnum<{
+            fruit: "fruit";
+            branch: "branch";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"webhook">;
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodEnum<{
+            POST: "POST";
+            PUT: "PUT";
+            GET: "GET";
+        }>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body_template: z.ZodPreprocess<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"send_mail">;
+        to: z.ZodString;
+        subject_template: z.ZodString;
+        body_template: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"edit_field">;
+        field: z.ZodString;
+        value: z.ZodUnknown;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"create_entry">;
+        seed_slug: z.ZodString;
+        field_map: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>;
+export declare const toggleAutomationSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type CreateAutomationBody = z.infer<typeof createAutomationSchema>;
+export type UpdateAutomationBody = z.infer<typeof updateAutomationSchema>;

package/dist/features/automations/context-resolver.d.ts

@@ -0,0 +1,8 @@
+import type { Automation } from '@beechcms/core';
+import type { ParsedKey } from './template-grammar';
+export interface ResolvedContext {
+    lookup(key: ParsedKey, onMissing?: (field: string) => void): unknown;
+    triggerEntry: Record<string, unknown> | null;
+}
+export declare function resolveAutomationContext(_automation: Automation, triggerEntry: Record<string, unknown> | null, batchEntries: Array<Record<string, unknown>>): Promise<ResolvedContext>;
+export declare function deriveEntryContext(base: ResolvedContext, entry: Record<string, unknown>): ResolvedContext;

package/dist/features/automations/cron-runner.d.ts

@@ -0,0 +1,9 @@
+import type { ContentRepository, IAutomationRepository, IIdGenerator, Seed } from '@beechcms/core';
+export interface CronRunnerDeps {
+    automationRepository: IAutomationRepository;
+    contentRepository: ContentRepository;
+    getSeed: (slug: string) => Seed | null;
+    env: Record<string, string | undefined>;
+    idGenerator: IIdGenerator;
+}
+export declare function runCronAutomations(deps: CronRunnerDeps, scheduledTime: number): Promise<void>;

package/dist/features/automations/cron-runner.utils.d.ts

@@ -0,0 +1 @@
+export declare function cronMatches(expression: string | null, scheduledTime: number): boolean;

package/dist/features/automations/filter-translation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared helper: converts a TriggerCondition into a FilterGroup accepted by
+ * ContentRepository.findMany. Used by cron-runner and context-resolver.
+ *
+ * TODO Sprint 8 (Task 12): when-pushdown.ts will call extractPushdownFilters
+ * to convert safe WhenNode predicates to FilterGroup[] for SQL pre-filtering.
+ */
+import type { FilterGroup, Seed, TriggerCondition } from '@beechcms/core';
+export declare function conditionToFilterGroup(c: TriggerCondition, seed: Seed): FilterGroup;

package/dist/features/automations/index.d.ts

@@ -0,0 +1,7 @@
+export { AutomationRunner } from './automation-runner';
+export type { AutomationRunnerDeps } from './automation-runner';
+export { runCronAutomations } from './cron-runner';
+export type { CronRunnerDeps } from './cron-runner';
+export { automationsApp } from './automations.handler';
+export { createAutomationSchema, updateAutomationSchema, toggleAutomationSchema, automationActionSchema, } from './automations.schema';
+export type { CreateAutomationBody, UpdateAutomationBody } from './automations.schema';

package/dist/features/automations/template-grammar.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure template-key parser for the automation template engine.
+ *
+ * Grammar (Sprint 6):
+ *   simple:  {{title}}, {{author.name}}
+ *   scoped:  {{<scope>:<selector>:<field>}}
+ *
+ * Grammar (Sprint 7):
+ *   var_access: {{varname.firstone.campo}}, {{varname.count.(status=paid)}}
+ *               {{varname.array[id1,id2].count}}
+ *
+ * Scopes: this | batch | <seedSlug> | <contextKey>
+ * Selectors: lastone | firstone | all | byid(<id>) | where(<alias>=<value>)
+ * Fields: branch alias, system column, or aggregate (count/sum/avg/min/max/pluck)
+ *
+ * Sugar:
+ *   {{batch:count}}        → batch:all:count
+ *   {{<scope>:<field>}}    → <scope>:lastone:<field>  (default selector)
+ *
+ * TODO Sprint 8: extend ParsedKey to support WhenOperand refs once the
+ * recursive when-group evaluator (Tasks 10-16) is implemented.
+ */
+export { AUTOMATION_RESERVED_WORDS } from '@beechcms/core';
+export type VarStep = {
+    type: 'field';
+    name: string;
+} | {
+    type: 'nav';
+    nav: 'firstone' | 'lastone';
+} | {
+    type: 'agg';
+    op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'pluck';
+    field?: string;
+} | {
+    type: 'array';
+    ids: string[];
+};
+export interface InlineCondition {
+    column: string;
+    op: '=' | '!=' | '<' | '>' | '<=' | '>=';
+    value: string;
+}
+export type AutomationContextSelector = {
+    kind: 'lastone';
+} | {
+    kind: 'firstone';
+} | {
+    kind: 'all';
+} | {
+    kind: 'byid';
+    id: string;
+} | {
+    kind: 'where';
+    alias: string;
+    value: string;
+};
+export type AggregateOp = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'pluck';
+export type ParsedKey = {
+    kind: 'simple';
+    path: string;
+} | {
+    kind: 'scoped';
+    scope: string;
+    selector: AutomationContextSelector;
+    op: 'field' | AggregateOp;
+    field: string | null;
+} | {
+    kind: 'var_access';
+    name: string;
+    steps: VarStep[];
+    conditions: InlineCondition[];
+};
+export declare function parseTemplateKey(raw: string): ParsedKey | null;

package/dist/features/automations/var-access-resolver.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedKey } from './template-grammar';
+type VarAccessParsed = Extract<ParsedKey, {
+    kind: 'var_access';
+}>;
+export declare function resolveVarAccess(parsed: VarAccessParsed, variables: Record<string, unknown>, onMissing?: (field: string) => void): unknown;
+export {};

package/dist/features/automations/when-evaluator.d.ts

@@ -0,0 +1,3 @@
+import type { WhenNode } from '@beechcms/core';
+import type { ResolvedContext } from './context-resolver';
+export declare function evaluateWhen(node: WhenNode | null, context: ResolvedContext): boolean;

package/dist/features/automations/when-pushdown.d.ts

@@ -0,0 +1,2 @@
+import type { WhenNode, FilterGroup, Seed } from '@beechcms/core';
+export declare function extractPushdownFilters(node: WhenNode | null, seed: Seed): FilterGroup[];

package/dist/features/backrefs/backrefs.handler.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../../types';
+export declare const backrefsApp: Hono<AppEnv, import("hono/types").BlankSchema, "/">;

package/dist/features/backrefs/d1-backref.repository.d.ts

@@ -0,0 +1,17 @@
+import type { BackrefSource, Seed } from '@beechcms/core';
+export interface BackrefItem {
+    id: string;
+    displayName: string | null;
+    status: string;
+    updated_at: number | null;
+}
+export interface QueryGroupResult {
+    items: BackrefItem[];
+    total: number;
+}
+export declare class D1BackrefRepository {
+    private readonly db;
+    constructor(db: D1Database);
+    entryExists(slug: string, id: string): Promise<boolean>;
+    queryGroup(source: BackrefSource, sourceSeed: Seed, targetId: string, limit: number, offset: number): Promise<QueryGroupResult>;
+}

package/dist/features/backrefs/index.d.ts

@@ -0,0 +1 @@
+export { backrefsApp } from './backrefs.handler';

package/dist/features/content/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const CONTENT_ERRORS: {
+    readonly INVALID_SLUG: "Invalid slug";
+    readonly INVALID_SLUG_OR_ID: "Invalid slug or id";
+    readonly INVALID_JSON_BODY: "Invalid JSON body";
+    readonly NOT_FOUND: "Not found";
+    readonly SEED_NOT_FOUND: "Seed not found";
+    readonly DATABASE_ERROR: "Database error";
+    readonly SLUG_CONFLICT: "Slug already exists for this schema";
+    readonly SENSITIVE_FIELD_EDIT: "Cannot edit sensitive fields";
+    readonly BULK_SIZE_EXCEEDED: "Cannot edit more than 500 entries at once";
+    readonly FIELD_NOT_BULK_EDITABLE: "Field cannot be bulk-edited";
+};

package/dist/features/content/handlers/bulk.handler.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function bulkHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/handlers/create.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function createHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/handlers/delete.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function deleteHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/handlers/facets.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function facetsHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/handlers/get.d.ts

@@ -0,0 +1,4 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function getByIdHandler(context: Context<AppEnv>): Promise<Response>;
+export declare function getBySlugHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/handlers/helpers.d.ts

@@ -0,0 +1,12 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function normalizeBody(raw: unknown): Record<string, unknown>;
+export declare function contentValidationProblem(context: Context, details: Array<{
+    field: string;
+    expected: string;
+    received: string;
+    message: string;
+}>): Response;
+export declare function logContentActivity(context: Context<AppEnv>, action: 'create' | 'update' | 'delete', id: string, slug: string, title: string): void;
+export declare function dispatchContentAutomation(context: Context<AppEnv>, seedSlug: string, event: 'create' | 'update' | 'delete', entry: Record<string, unknown>): void;
+export declare function handleContentDatabaseError(context: Context<AppEnv>, error: unknown): Response;

package/dist/features/content/handlers/list.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function listHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/handlers/update.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'hono';
+import { AppEnv } from '../../../types';
+export declare function updateHandler(context: Context<AppEnv>): Promise<Response>;

package/dist/features/content/index.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import { AppEnv } from '../../types';
+declare const content: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+export default content;

package/dist/features/dashboard-layout/dashboard-layout.handler.d.ts

@@ -0,0 +1,7 @@
+import { Hono } from 'hono';
+import type { Env, Variables } from '../../types';
+declare const dashboardLayoutApp: Hono<{
+    Bindings: Env;
+    Variables: Variables;
+}, import("hono/types").BlankSchema, "/">;
+export { dashboardLayoutApp };

package/dist/features/dashboard-layout/index.d.ts

@@ -0,0 +1 @@
+export { dashboardLayoutApp } from './dashboard-layout.handler';

package/dist/features/draft/draft.handler.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import { AppEnv } from '../../types';
+declare const draftApp: Hono<AppEnv, import("hono/types").BlankSchema, "/">;
+export { draftApp };

package/dist/features/draft/draft.middleware.d.ts

@@ -0,0 +1,9 @@
+import type { AppEnv } from '../../types';
+/**
+ * Middleware that guards draft-related endpoints.
+ * Responsibilities:
+ * 1. Validates that the targeted Seed schema exists.
+ * 2. Ensures the Seed configuration explicitly allows drafts.
+ * 3. Confirms that the main live content entry exists in the repository.
+ */
+export declare const draftGuard: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;

package/dist/features/draft/index.d.ts

@@ -0,0 +1 @@
+export { draftApp } from './draft.handler';

package/{src/features/email/email.provider.ts → dist/features/email/email.provider.d.ts}

@@ -1,9 +1,4 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import type { OutboundEmail } from './email.types'
-
+import type { OutboundEmail } from './email.types';
 /**
  * EmailProvider — formal contract for email sending providers.
  *
@@ -21,22 +16,22 @@ import type { OutboundEmail } from './email.types'
  * ─────────────────────────────────────────────────────────────────────────────
  */
 export interface EmailProvider {
-  /**
-   * Sends a single transactional email.
-   *
-   * @param email - The fully resolved message: sender, recipient,
-   *               subject, and HTML body. Use the builders in `templates/` to
-   *               construct this object correctly.
-   *
-   * @returns Promise that resolves when the provider has **accepted** the
-   *          message for delivery. Acceptance does not guarantee delivery
-   *          to the inbox — that depends on the recipient's server and the
-   *          provider's deliverability.
-   *
-   * @throws {Error} If the provider rejects the request (failed authentication,
-   *                 network error, invalid payload). The caller
-   *                 (`email.service.ts`) is responsible for catching and handling
-   *                 this error appropriately.
-   */
-  send(email: OutboundEmail): Promise<void>
+    /**
+     * Sends a single transactional email.
+     *
+     * @param email - The fully resolved message: sender, recipient,
+     *               subject, and HTML body. Use the builders in `templates/` to
+     *               construct this object correctly.
+     *
+     * @returns Promise that resolves when the provider has **accepted** the
+     *          message for delivery. Acceptance does not guarantee delivery
+     *          to the inbox — that depends on the recipient's server and the
+     *          provider's deliverability.
+     *
+     * @throws {Error} If the provider rejects the request (failed authentication,
+     *                 network error, invalid payload). The caller
+     *                 (`email.service.ts`) is responsible for catching and handling
+     *                 this error appropriately.
+     */
+    send(email: OutboundEmail): Promise<void>;
 }

package/dist/features/email/email.service.d.ts

@@ -0,0 +1,13 @@
+import type { PasswordResetEmailParams, PasswordChangedEmailParams, AutomationMailParams } from './email.types';
+export interface EmailProviderEnv {
+    /** "smtp" | "resend"; default "resend" if absent */
+    provider?: string;
+    /** Resend API key, used when provider is "resend" */
+    apiKey?: string;
+    /** Mailpit base URL (e.g. http://localhost:8025), used when provider is "smtp" */
+    smtpBaseUrl?: string;
+    isDev?: boolean;
+}
+export declare function sendPasswordResetEmail(params: PasswordResetEmailParams): Promise<void>;
+export declare function sendPasswordChangedEmail(params: PasswordChangedEmailParams): Promise<void>;
+export declare function sendAutomationMail(params: AutomationMailParams): Promise<void>;

package/dist/features/email/email.types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared types for the Beech CMS email module.
+ *
+ * All types used across provider, service, and templates are defined here
+ * so that each layer remains decoupled from the others.
+ */
+/**
+ * Supported languages for the email template system.
+ *
+ * To add a new language:
+ *  1. Add the ISO code here (e.g., `'fr'`).
+ *  2. Add the corresponding translation in the `COPY` object of every
+ *     file in `templates/`. TypeScript will flag missing keys.
+ */
+export declare const SUPPORTED_EMAIL_LOCALES: readonly ["en", "it"];
+export type EmailLocale = (typeof SUPPORTED_EMAIL_LOCALES)[number];
+/**
+ * Resolves an unverified locale string (e.g., from a request body)
+ * to a supported `EmailLocale` value. Any unknown value
+ * safely falls back to `'en'`.
+ *
+ * @param raw - Raw value from the client (can be anything).
+ * @returns A valid `EmailLocale`, always.
+ */
+export declare function resolveEmailLocale(raw: unknown): EmailLocale;
+/**
+ * The resolved email message that the provider receives and sends.
+ * It is constructed by the service by combining the call parameters
+ * with the template builder output.
+ */
+export interface OutboundEmail {
+    /** Sender address in RFC 5321 format (e.g., "Beech CMS <noreply@beechcms.dev>"). */
+    from: string;
+    /** List of recipient addresses. Must contain at least one element. */
+    to: string[];
+    subject: string;
+    /** Complete HTML body. Must be a valid HTML document (see `templates/shell.ts`). */
+    html: string;
+}
+/**
+ * Shared parameters for every email sending function in `email.service.ts`.
+ * Specific functions extend this type with the additional fields
+ * required for their respective templates.
+ */
+export interface BaseEmailParams {
+    /** Main recipient address. */
+    to: string;
+    /** Email body language. Use `resolveEmailLocale()` before passing it here. */
+    locale: EmailLocale;
+    /**
+     * Resend API key (or the active provider's key). Must be non-empty —
+     * the caller is responsible for validating it before invoking the service.
+     */
+    apiKey: string;
+    /**
+     * Sender address in RFC 5321 format.
+     * Default: "Beech CMS <onboarding@resend.dev>" (Resend test sender).
+     * In production, set a verified address via the
+     * `EMAIL_FROM` environment variable.
+     */
+    from?: string;
+    /**
+     * When `true`, provider errors are logged to the console.
+     * Set to `false` in production to avoid exposing internal details.
+     */
+    isDev?: boolean;
+}
+/** Parameters for the password reset email — adds the reset URL. */
+export interface PasswordResetEmailParams extends BaseEmailParams {
+    /**
+     * Complete URL that the user clicks to set the new password.
+     * Contains the token in plain text as a query param `?token=<uuid>`.
+     * Constructed by the caller as `${APP_URL}/reset-password?token=${token}`.
+     */
+    resetUrl: string;
+    provider?: 'smtp' | 'resend';
+    smtpBaseUrl?: string;
+}
+/** Parameters for the "password changed" notification. No additional fields. */
+export interface PasswordChangedEmailParams extends BaseEmailParams {
+    provider?: 'smtp' | 'resend';
+    smtpBaseUrl?: string;
+}
+export interface AutomationMailParams {
+    to: string;
+    subject: string;
+    /** Plain text or HTML — passed verbatim to provider. */
+    body: string;
+    apiKey?: string;
+    resendApiKey?: string;
+    from?: string;
+    provider?: 'smtp' | 'resend';
+    smtpBaseUrl?: string;
+}

package/{src/features/email/index.ts → dist/features/email/index.d.ts}

@@ -1,7 +1,3 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
 /**
  * Public API — modulo email di Beech CMS
  *
@@ -19,15 +15,6 @@
  *   PasswordResetEmailParams  — shape dei parametri per sendPasswordResetEmail
  *   PasswordChangedEmailParams — shape dei parametri per sendPasswordChangedEmail
  */
-
-export { sendPasswordResetEmail, sendPasswordChangedEmail, sendAutomationMail } from './email.service'
-export {
-  resolveEmailLocale,
-  SUPPORTED_EMAIL_LOCALES,
-} from './email.types'
-export type {
-  EmailLocale,
-  PasswordResetEmailParams,
-  PasswordChangedEmailParams,
-  AutomationMailParams,
-} from './email.types'
+export { sendPasswordResetEmail, sendPasswordChangedEmail, sendAutomationMail } from './email.service';
+export { resolveEmailLocale, SUPPORTED_EMAIL_LOCALES, } from './email.types';
+export type { EmailLocale, PasswordResetEmailParams, PasswordChangedEmailParams, AutomationMailParams, } from './email.types';