@rovela-ai/sdk 0.22.0 → 0.24.0

package/dist/emails/transport-smtp.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @rovela/sdk/emails/transport-smtp
+ *
+ * The nodemailer-touching half of the email transport (SDK 0.23.0),
+ * isolated in its own module. nodemailer pulls node builtins (net/tls/dns),
+ * and the emails graph is CLIENT-REACHABLE (the §62 invariant: auth barrel →
+ * send → sender → transport) — so it is loaded through a BUNDLER-IGNORED
+ * dynamic import:
+ *
+ *   import(\/* webpackIgnore *\/ \/* turbopackIgnore *\/ 'nodemailer')
+ *
+ * Both bundlers skip the specifier entirely (no client-side resolution, no
+ * chunk), and at server runtime it is a NATIVE import with real Node
+ * resolution from the executing module's location — no path guessing, no
+ * eval tricks. Two consequences, both handled at the packaging layer:
+ *
+ *   - nodemailer is a TEMPLATE dependency (store package.json), so it sits
+ *     hoisted at the app root deterministically (an SDK-transitive-only
+ *     install can nest it where a bundled chunk can't resolve it).
+ *   - Vercel's file tracer can't see an ignored import — the template's
+ *     next.config pins outputFileTracingIncludes: node_modules/nodemailer/**
+ *     (the E4 blueprint.json precedent).
+ *
+ * A load failure logs LOUDLY (fail-safe rule: the send falls back to the
+ * platform path, but ops must see WHY smtp was unavailable) and the cached
+ * promise resets so a transient failure can retry.
+ */
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string | null;
+    password: string | null;
+}
+export interface SmtpSendInput {
+    fromAddress: string;
+    fromName: string;
+    to: string;
+    subject: string;
+    html: string;
+    replyTo?: string;
+}
+export interface SmtpSendResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+export declare function sendViaSmtp(input: SmtpSendInput, cfg: SmtpConfig): Promise<SmtpSendResult>;
+/**
+ * Save-time SMTP validation — a real handshake (connect + EHLO + auth), no
+ * email sent. Used by the admin Sending panel so misconfiguration surfaces
+ * at save time instead of silently pushing every send onto the fallback.
+ */
+export declare function verifySmtp(cfg: SmtpConfig): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=transport-smtp.d.ts.map

package/dist/emails/transport-smtp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-smtp.d.ts","sourceRoot":"","sources":["../../src/emails/transport-smtp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAWH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AA2CD,wBAAsB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAgBhG;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAS1F"}

package/dist/emails/transport-smtp.js

@@ -0,0 +1,97 @@
+/**
+ * @rovela/sdk/emails/transport-smtp
+ *
+ * The nodemailer-touching half of the email transport (SDK 0.23.0),
+ * isolated in its own module. nodemailer pulls node builtins (net/tls/dns),
+ * and the emails graph is CLIENT-REACHABLE (the §62 invariant: auth barrel →
+ * send → sender → transport) — so it is loaded through a BUNDLER-IGNORED
+ * dynamic import:
+ *
+ *   import(\/* webpackIgnore *\/ \/* turbopackIgnore *\/ 'nodemailer')
+ *
+ * Both bundlers skip the specifier entirely (no client-side resolution, no
+ * chunk), and at server runtime it is a NATIVE import with real Node
+ * resolution from the executing module's location — no path guessing, no
+ * eval tricks. Two consequences, both handled at the packaging layer:
+ *
+ *   - nodemailer is a TEMPLATE dependency (store package.json), so it sits
+ *     hoisted at the app root deterministically (an SDK-transitive-only
+ *     install can nest it where a bundled chunk can't resolve it).
+ *   - Vercel's file tracer can't see an ignored import — the template's
+ *     next.config pins outputFileTracingIncludes: node_modules/nodemailer/**
+ *     (the E4 blueprint.json precedent).
+ *
+ * A load failure logs LOUDLY (fail-safe rule: the send falls back to the
+ * platform path, but ops must see WHY smtp was unavailable) and the cached
+ * promise resets so a transient failure can retry.
+ */
+// =============================================================================
+// Loader
+// =============================================================================
+let nodemailerPromise = null;
+function loadNodemailer() {
+    if (!nodemailerPromise) {
+        nodemailerPromise = import(
+        /* webpackIgnore: true */ /* turbopackIgnore: true */ 'nodemailer')
+            .then((m) => (m.default ??
+            m))
+            .catch((err) => {
+            console.error('[Email] nodemailer not loadable:', err);
+            nodemailerPromise = null; // allow retry on transient failures
+            return null;
+        });
+    }
+    return nodemailerPromise;
+}
+function buildTransport(nm, cfg) {
+    return nm.createTransport({
+        host: cfg.host,
+        port: cfg.port,
+        secure: cfg.secure,
+        ...(cfg.user ? { auth: { user: cfg.user, pass: cfg.password ?? '' } } : {}),
+        connectionTimeout: 10000,
+        greetingTimeout: 10000,
+        socketTimeout: 15000,
+    });
+}
+// =============================================================================
+// Send + verify
+// =============================================================================
+export async function sendViaSmtp(input, cfg) {
+    const nm = await loadNodemailer();
+    if (!nm)
+        return { success: false, error: 'SMTP transport unavailable (nodemailer not loadable)' };
+    if (!input.fromAddress)
+        return { success: false, error: 'No sender address configured' };
+    try {
+        const info = await buildTransport(nm, cfg).sendMail({
+            from: `${input.fromName} <${input.fromAddress}>`,
+            to: input.to,
+            subject: input.subject,
+            html: input.html,
+            ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+        });
+        return { success: true, messageId: info?.messageId };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : 'SMTP send failed' };
+    }
+}
+/**
+ * Save-time SMTP validation — a real handshake (connect + EHLO + auth), no
+ * email sent. Used by the admin Sending panel so misconfiguration surfaces
+ * at save time instead of silently pushing every send onto the fallback.
+ */
+export async function verifySmtp(cfg) {
+    const nm = await loadNodemailer();
+    if (!nm)
+        return { ok: false, error: 'SMTP transport unavailable (nodemailer not loadable)' };
+    try {
+        await buildTransport(nm, cfg).verify();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : 'SMTP verification failed' };
+    }
+}
+//# sourceMappingURL=transport-smtp.js.map

package/dist/emails/transport-smtp.js.map

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

package/dist/emails/transport.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @rovela/sdk/emails/transport
+ *
+ * Transactional-email transport resolution (SDK 0.23.0). Every send funnels
+ * through sendEmail() (sender.ts), which asks this module HOW to deliver:
+ *
+ *   - 'platform' (default, also NULL) — the platform Resend sender. The
+ *     entire pre-0.23 fleet stays byte-identical on this path.
+ *   - 'brevo'    — Brevo's transactional HTTP API (POST /v3/smtp/email)
+ *     using the SAME store_settings.brevo_api_key the marketing integration
+ *     stores. No SMTP key needed — this is what makes the integrations-page
+ *     toggle seamless. Sender address must be a VERIFIED Brevo sender or
+ *     Brevo rejects the send (surfaced at save time by the admin UI).
+ *   - 'smtp'     — the merchant's own SMTP server via nodemailer.
+ *
+ * FAIL-SAFE DELIVERY RULE (load-bearing): a non-platform transport failure
+ * falls back to the platform Resend path and logs loudly — a merchant's
+ * SMTP typo must never eat an order confirmation. Misconfiguration is
+ * caught at SAVE time by the admin Sending panel, not at send time.
+ *
+ * CLIENT-REACHABILITY (load-bearing, the §62 emails-graph invariant): this
+ * file is reachable from client bundles (auth barrel → send → sender →
+ * transport). All nodemailer-touching code lives in ./transport-smtp, which
+ * loads it via a BUNDLER-IGNORED dynamic import (webpackIgnore +
+ * turbopackIgnore) — native server-runtime resolution, nothing for the
+ * client bundler to resolve. Fails open to the platform path when the
+ * module can't load. See transport-smtp.ts for the packaging contract
+ * (template dependency + tracing include).
+ */
+import { type StoreSettingsData } from '../core/db/queries';
+import { type SmtpConfig as SmtpConfigType } from './transport-smtp';
+export type EmailTransportKind = 'platform' | 'brevo' | 'smtp';
+export interface TransportSendInput {
+    from: string;
+    fromAddress: string;
+    fromName: string;
+    to: string;
+    subject: string;
+    html: string;
+    replyTo?: string;
+}
+export interface TransportSendResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+/** The store's configured transport ('platform' when unset/unknown). */
+export declare function resolveTransportKind(settings: Pick<StoreSettingsData, 'emailTransport'> | null): EmailTransportKind;
+/**
+ * Sender identity for non-platform transports. The platform path keeps its
+ * existing RESEND_FROM_EMAIL resolution untouched; brevo/smtp REQUIRE a
+ * merchant-owned from-address (their domain, their reputation) and fall
+ * back to the store contact email when the dedicated field is empty.
+ */
+export declare function resolveFromIdentity(settings: Pick<StoreSettingsData, 'emailFromAddress' | 'emailFromName' | 'storeEmail' | 'storeName'> | null): {
+    address: string | null;
+    name: string;
+};
+/** Server-only read of the marketing integration's key (card-added columns). */
+export declare function getBrevoApiKey(): Promise<string | null>;
+export { verifySmtp } from './transport-smtp';
+export type { SmtpConfig } from './transport-smtp';
+export declare function smtpConfigFromSettings(settings: Pick<StoreSettingsData, 'smtpHost' | 'smtpPort' | 'smtpSecure' | 'smtpUser' | 'smtpPassword'> | null): SmtpConfigType | null;
+export interface TransportDispatch {
+    kind: EmailTransportKind;
+    /** null → caller proceeds with the platform Resend path. */
+    send: ((input: TransportSendInput) => Promise<TransportSendResult>) | null;
+    /** Merchant sender identity for non-platform transports. */
+    fromAddress: string | null;
+    fromName: string;
+}
+/**
+ * Resolve the store's transport once per send. Any resolution failure
+ * degrades to the platform path (fail-safe delivery rule).
+ */
+export declare function resolveTransport(): Promise<TransportDispatch>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/emails/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/emails/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAEzE,OAAO,EAAe,KAAK,UAAU,IAAI,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAMjF,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAA;AAE9D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD,wEAAwE;AACxE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,GAAG,IAAI,GACzD,kBAAkB,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,GAAG,eAAe,GAAG,YAAY,GAAG,WAAW,CAAC,GAAG,IAAI,GAC1G;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAI1C;AAMD,gFAAgF;AAChF,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAY7D;AAkCD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,cAAc,CAAC,GAAG,IAAI,GAC7G,cAAc,GAAG,IAAI,CAYvB;AAMD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,kBAAkB,CAAA;IACxB,4DAA4D;IAC5D,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG,IAAI,CAAA;IAC1E,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAoCnE"}

package/dist/emails/transport.js

@@ -0,0 +1,154 @@
+/**
+ * @rovela/sdk/emails/transport
+ *
+ * Transactional-email transport resolution (SDK 0.23.0). Every send funnels
+ * through sendEmail() (sender.ts), which asks this module HOW to deliver:
+ *
+ *   - 'platform' (default, also NULL) — the platform Resend sender. The
+ *     entire pre-0.23 fleet stays byte-identical on this path.
+ *   - 'brevo'    — Brevo's transactional HTTP API (POST /v3/smtp/email)
+ *     using the SAME store_settings.brevo_api_key the marketing integration
+ *     stores. No SMTP key needed — this is what makes the integrations-page
+ *     toggle seamless. Sender address must be a VERIFIED Brevo sender or
+ *     Brevo rejects the send (surfaced at save time by the admin UI).
+ *   - 'smtp'     — the merchant's own SMTP server via nodemailer.
+ *
+ * FAIL-SAFE DELIVERY RULE (load-bearing): a non-platform transport failure
+ * falls back to the platform Resend path and logs loudly — a merchant's
+ * SMTP typo must never eat an order confirmation. Misconfiguration is
+ * caught at SAVE time by the admin Sending panel, not at send time.
+ *
+ * CLIENT-REACHABILITY (load-bearing, the §62 emails-graph invariant): this
+ * file is reachable from client bundles (auth barrel → send → sender →
+ * transport). All nodemailer-touching code lives in ./transport-smtp, which
+ * loads it via a BUNDLER-IGNORED dynamic import (webpackIgnore +
+ * turbopackIgnore) — native server-runtime resolution, nothing for the
+ * client bundler to resolve. Fails open to the platform path when the
+ * module can't load. See transport-smtp.ts for the packaging contract
+ * (template dependency + tracing include).
+ */
+import { findSettings } from '../core/db/queries';
+import { getSql } from '../core/db/client';
+import { sendViaSmtp } from './transport-smtp';
+// =============================================================================
+// Resolution
+// =============================================================================
+/** The store's configured transport ('platform' when unset/unknown). */
+export function resolveTransportKind(settings) {
+    const t = settings?.emailTransport;
+    return t === 'brevo' || t === 'smtp' ? t : 'platform';
+}
+/**
+ * Sender identity for non-platform transports. The platform path keeps its
+ * existing RESEND_FROM_EMAIL resolution untouched; brevo/smtp REQUIRE a
+ * merchant-owned from-address (their domain, their reputation) and fall
+ * back to the store contact email when the dedicated field is empty.
+ */
+export function resolveFromIdentity(settings) {
+    const address = settings?.emailFromAddress?.trim() || settings?.storeEmail?.trim() || null;
+    const name = settings?.emailFromName?.trim() || settings?.storeName?.trim() || 'Our Store';
+    return { address, name };
+}
+// =============================================================================
+// Brevo transport (HTTP API — no SMTP key needed)
+// =============================================================================
+/** Server-only read of the marketing integration's key (card-added columns). */
+export async function getBrevoApiKey() {
+    try {
+        const sql = getSql();
+        const rows = (await sql `
+      SELECT brevo_api_key FROM store_settings LIMIT 1
+    `);
+        return rows[0]?.brevo_api_key || null;
+    }
+    catch {
+        // Column absent (integration never installed) or transient DB error —
+        // the caller falls back to the platform path.
+        return null;
+    }
+}
+async function sendViaBrevo(input) {
+    const apiKey = await getBrevoApiKey();
+    if (!apiKey)
+        return { success: false, error: 'Brevo API key is not configured' };
+    if (!input.fromAddress)
+        return { success: false, error: 'No sender address configured' };
+    try {
+        const res = await fetch('https://api.brevo.com/v3/smtp/email', {
+            method: 'POST',
+            headers: { 'api-key': apiKey, 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify({
+                sender: { email: input.fromAddress, name: input.fromName },
+                to: [{ email: input.to }],
+                subject: input.subject,
+                htmlContent: input.html,
+                ...(input.replyTo ? { replyTo: { email: input.replyTo } } : {}),
+            }),
+            signal: AbortSignal.timeout(15000),
+        });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok) {
+            return { success: false, error: body?.message || `Brevo HTTP ${res.status}` };
+        }
+        return { success: true, messageId: body?.messageId };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : 'Brevo send failed' };
+    }
+}
+// =============================================================================
+// SMTP transport — nodemailer isolated in ./transport-smtp
+// =============================================================================
+export { verifySmtp } from './transport-smtp';
+export function smtpConfigFromSettings(settings) {
+    const host = settings?.smtpHost?.trim();
+    if (!host)
+        return null;
+    const port = settings?.smtpPort ?? 587;
+    return {
+        host,
+        port,
+        // Convention: explicit flag wins; otherwise 465 implies implicit TLS.
+        secure: settings?.smtpSecure ?? port === 465,
+        user: settings?.smtpUser?.trim() || null,
+        password: settings?.smtpPassword || null,
+    };
+}
+/**
+ * Resolve the store's transport once per send. Any resolution failure
+ * degrades to the platform path (fail-safe delivery rule).
+ */
+export async function resolveTransport() {
+    let settings = null;
+    try {
+        settings = await findSettings();
+    }
+    catch {
+        settings = null;
+    }
+    const kind = resolveTransportKind(settings);
+    const identity = resolveFromIdentity(settings);
+    if (kind === 'brevo') {
+        return { kind, send: sendViaBrevo, fromAddress: identity.address, fromName: identity.name };
+    }
+    if (kind === 'smtp') {
+        const cfg = smtpConfigFromSettings(settings);
+        if (cfg) {
+            return {
+                kind,
+                send: (input) => sendViaSmtp({
+                    fromAddress: input.fromAddress,
+                    fromName: input.fromName,
+                    to: input.to,
+                    subject: input.subject,
+                    html: input.html,
+                    replyTo: input.replyTo,
+                }, cfg),
+                fromAddress: identity.address,
+                fromName: identity.name,
+            };
+        }
+    }
+    return { kind: 'platform', send: null, fromAddress: identity.address, fromName: identity.name };
+}
+//# sourceMappingURL=transport.js.map

package/dist/emails/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/emails/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAA0B,MAAM,oBAAoB,CAAA;AACzE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAqC,MAAM,kBAAkB,CAAA;AAwBjF,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF,wEAAwE;AACxE,MAAM,UAAU,oBAAoB,CAClC,QAA0D;IAE1D,MAAM,CAAC,GAAG,QAAQ,EAAE,cAAc,CAAA;IAClC,OAAO,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA2G;IAE3G,MAAM,OAAO,GAAG,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,IAAI,CAAA;IAC1F,MAAM,IAAI,GAAG,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,WAAW,CAAA;IAC1F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC1B,CAAC;AAED,gFAAgF;AAChF,kDAAkD;AAClD,gFAAgF;AAEhF,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAA;QACpB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAA;;KAEtB,CAA4C,CAAA;QAC7C,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,IAAI,IAAI,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,8CAA8C;QAC9C,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,KAAyB;IACnD,MAAM,MAAM,GAAG,MAAM,cAAc,EAAE,CAAA;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iCAAiC,EAAE,CAAA;IAChF,IAAI,CAAC,KAAK,CAAC,WAAW;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAA;IAExF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,qCAAqC,EAAE;YAC7D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,EAAE,kBAAkB,EAAE;YAC9F,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE;gBAC1D,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;gBACzB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,WAAW,EAAE,KAAK,CAAC,IAAI;gBACvB,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChE,CAAC;YACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC;SACnC,CAAC,CAAA;QACF,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAoD,CAAA;QACpG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,IAAI,cAAc,GAAG,CAAC,MAAM,EAAE,EAAE,CAAA;QAC/E,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAA;IAC5F,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,2DAA2D;AAC3D,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,MAAM,UAAU,sBAAsB,CACpC,QAA8G;IAE9G,MAAM,IAAI,GAAG,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;IACvC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,MAAM,IAAI,GAAG,QAAQ,EAAE,QAAQ,IAAI,GAAG,CAAA;IACtC,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,sEAAsE;QACtE,MAAM,EAAE,QAAQ,EAAE,UAAU,IAAI,IAAI,KAAK,GAAG;QAC5C,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,IAAI;QACxC,QAAQ,EAAE,QAAQ,EAAE,YAAY,IAAI,IAAI;KACzC,CAAA;AACH,CAAC;AAeD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,QAAQ,GAA6B,IAAI,CAAA;IAC7C,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,YAAY,EAAE,CAAA;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,IAAI,CAAA;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAA;IAC3C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IAE9C,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAA;IAC7F,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAA;QAC5C,IAAI,GAAG,EAAE,CAAC;YACR,OAAO;gBACL,IAAI;gBACJ,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CACd,WAAW,CACT;oBACE,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;iBACvB,EACD,GAAG,CACJ;gBACH,WAAW,EAAE,QAAQ,CAAC,OAAO;gBAC7B,QAAQ,EAAE,QAAQ,CAAC,IAAI;aACxB,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAA;AACjG,CAAC"}

package/docs/changelog/epoch-10-email-transport.md

@@ -0,0 +1,97 @@
+# E10 Email sending & Brevo — 0.23.0..0.23.0
+
+## What landed
+Transactional-email delivery became merchant-configurable. Every store email
+(order confirmations, account emails, custom emails) already funnels through
+the SDK's one `sendEmail()` chokepoint; it now resolves a per-store
+TRANSPORT: `'platform'` (default — the pre-0.23 Resend path, byte-identical
+for the whole fleet), `'brevo'` (the store's connected Brevo account over
+its HTTP API — same API key as the marketing integration, no SMTP key
+needed), or `'smtp'` (the merchant's own server). The Brevo integration
+also gained a live status echo and a one-click, resumable HISTORY IMPORT
+that replaces per-store backfill scripts.
+
+## SDK-internal (free via pin bump)
+- `emails/transport.ts` — transport resolution + the two senders. **FAIL-SAFE
+  DELIVERY RULE**: a non-platform transport failure falls back to the
+  platform Resend path and logs loudly; a merchant's SMTP typo can never eat
+  an order confirmation. Misconfiguration surfaces at SAVE time instead
+  (real SMTP `verify()` handshake; Brevo verified-sender check).
+- New `store_settings` columns (drizzle + `ensureStoreSettingsSchema` +
+  parent-branch ALTER at ship time): `email_transport`,
+  `email_from_address`, `email_from_name`, `smtp_host`, `smtp_port`,
+  `smtp_secure`, `smtp_user`, `smtp_password` (SERVER-ONLY secret — stripped
+  from the admin settings GET like `colissimo_password`; write-only, blank
+  keeps the stored value).
+- `nodemailer` (pinned to the 7.x line — next-auth 4.x declares
+  `peerOptional nodemailer@^7` and npm refuses to hoist a different major)
+  became BOTH an SDK dependency and a TEMPLATE dependency (root-hoisted,
+  deterministic location). It loads through a BUNDLER-IGNORED dynamic
+  import (`webpackIgnore` + `turbopackIgnore`, isolated in
+  `emails/transport-smtp.ts`) — the emails graph is client-reachable, so a
+  static import breaks `next build`; the ignored import is native
+  server-runtime resolution, no path guessing.
+- `EmailSendingPanel` (Sending card on /admin/emails) + `EmailsManager`
+  mounts it; the "Send a test" button exercises the REAL saved transport.
+- Integrations registry entries gained `details` bullets (what each
+  integration actually does, rendered in the configure modal — all 10
+  entries authored).
+- Brevo configure modal extras: live "Connected as x@y · plan" echo,
+  verified-sender status, the "send transactional emails through Brevo"
+  toggle (writes the same `email_transport` column as the Sending panel —
+  the two surfaces can never disagree), and the history import UI
+  (progress bar, resumable, include-orders switch defaulted OFF when
+  Brevo's eCommerce module already holds orders — the double-count guard).
+
+## Template contract
+- `app/api/admin/emails/sending/route.ts` (NEW) — re-export
+  `getEmailSending as GET, putEmailSending as PUT`. Without it the Sending
+  panel shows a load error and the Brevo toggle cannot save.
+- `app/api/admin/integrations/brevo/route.ts` (NEW) — `getBrevoStatus as
+  GET`; `app/api/admin/integrations/brevo/backfill/route.ts` (NEW) —
+  `postBrevoBackfill as POST`. Without them the Brevo modal's extras show
+  an error state (credentials editing keeps working).
+- **Component-dependency note (the E4 precedent)**: two per-store
+  requirements for the Custom-SMTP option — `package.json` gains
+  `"nodemailer": "7.0.13"` (MUST stay on 7.x: next-auth's peerOptional
+  range; a 8/9 pin makes npm nest it where the runtime can't resolve it)
+  and `next.config.js` gains
+  `outputFileTracingIncludes: ['./node_modules/nodemailer/**']` (an ignored
+  import is invisible to Vercel's tracer). A store updating the SDK WITHOUT
+  these loses only the Custom-SMTP option at runtime (platform + Brevo
+  transports are unaffected — Brevo is plain fetch), with a loud
+  `[Email] nodemailer not loadable` log.
+
+## Behavior contracts
+- `sendEmail()` behavior is UNCHANGED while `email_transport` is NULL /
+  'platform' — the entire existing fleet keeps its exact sending path.
+- The Brevo history import is idempotent + resumable: contacts upsert by
+  email (`updateEnabled` — no duplicates, existing attributes/lists/consent
+  untouched, NO listIds ever sent), orders push with `historical: true`
+  (populates dashboards, NEVER fires an automation), chunked per request
+  (serverless-safe; the modal loops on the returned cursor).
+- Per-store backfill scripts are RETIRED: the connect-brevo card + the
+  credentials contract now forbid writing one-off sync scripts into the
+  repo — history imports live in the admin.
+
+## Custom-code hazards (audit greps for CC)
+- Grep `scripts/` for hand-written Brevo/marketing backfill or sync scripts
+  (e.g. EasyElec's `scripts/brevo-backfill.mjs`) — superseded by
+  Integrations → Brevo → "Import history"; delete them.
+- Grep for direct `getResend()` / `resend.emails.send` calls in store code —
+  they bypass the transport layer; route them through `sendEmail()` from
+  `@rovela-ai/sdk/emails`.
+
+## MERCHANT-DATA HAZARD
+None — no existing data changes meaning. The default transport is the
+existing behavior; Brevo/SMTP are opt-in.
+
+## Verify
+- /admin/emails shows the Sending card; saving Custom SMTP with a wrong
+  host is REJECTED at save time with the handshake error.
+- With Brevo connected: the integration modal shows "Connected as …", the
+  transactional toggle flips `email_transport`, and "Send a test" delivers
+  through Brevo (check the Brevo → Transactional log).
+- The history import runs to 100% with a progress bar, is resumable after
+  an interruption, and fires zero automations (historical flag).
+- A store with `email_transport` unset sends exactly as before.

package/docs/changelog/epoch-11-order-extras.md

@@ -0,0 +1,42 @@
+# E11 Order custom fields — 0.24.0..0.24.0
+
+## What landed
+Orders gained a custom-fields slot: `orders.metafields` — the exact mirror of
+`products.metafields` (`[{ key, label, value }]` jsonb). It exists so
+order-level details from an imported platform have somewhere to live (the
+PrestaShop importer maps extras like the recyclable-packaging flag, gift
+message, payment-method label, and the merchant's ORIGINAL order reference
+into it). Import-owned in v1: the admin renders it read-only, there is no
+editing UI, and native Rovela checkout does not write it.
+
+## SDK-internal (free via pin bump)
+- `core/db/schema.ts` — `orders.metafields jsonb NOT NULL DEFAULT '[]'`,
+  self-healed via `ensurePaymentMethodsSchema` (the orders chokepoint that
+  guards every full-row order read), parent-branch ALTER run at ship time.
+- `admin/components/OrderDetails.tsx` — an "Additional details" card in the
+  right column (below Payment): label → value rows, hidden entirely when the
+  order has no metafields.
+- `admin/types.ts` — `AdminOrderDetail.metafields`.
+
+## Template contract
+No new mounts, no new routes, no new dependencies — the card renders from the
+existing `/api/admin/orders/[id]` GET (a full-row select). A plain pin bump
+is the whole update.
+
+## Behavior contracts
+- Orders without metafields render byte-identically to 0.23 — the card only
+  appears when the array is non-empty.
+- The platform's export API (`/api/v1/orders`) serves `metafields` as an
+  optional newer-store column (null/empty on branches that predate it).
+
+## Custom-code hazards (audit greps for CC)
+- None specific to this epoch. Stores with custom order-detail pages built
+  from the same GET simply ignore the new field.
+
+## MERCHANT-DATA HAZARD
+None — purely additive; no existing data changes meaning.
+
+## Verify
+- Open any order in /admin — no "Additional details" card (empty metafields).
+- After a PrestaShop import with order fields mapped, imported orders show
+  the card with the mapped values (e.g. "Recyclable packaging: Yes").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rovela-ai/sdk",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Rovela SDK - Pre-built e-commerce components for AI-powered store generation",
   "type": "module",
   "license": "MIT",
@@ -320,6 +320,7 @@
     "lucide-react": "0.555.0",
     "nanoid": "5.1.6",
     "next-auth": "4.24.13",
+    "nodemailer": "7.0.13",
     "react-colorful": "^5.6.1",
     "recharts": "3.7.0",
     "resend": "6.9.1",

package/templates/store-template/app/api/admin/emails/sending/route.ts

@@ -0,0 +1,9 @@
+/**
+ * Email Sending Configuration Route
+ *
+ * GET /api/admin/emails/sending - Current transactional-email transport
+ * PUT /api/admin/emails/sending - Save it (SMTP handshake / Brevo verified-
+ *                                 sender check run BEFORE persisting)
+ */
+
+export { getEmailSending as GET, putEmailSending as PUT } from '@rovela-ai/sdk/admin/api'

package/templates/store-template/app/api/admin/integrations/brevo/backfill/route.ts

@@ -0,0 +1,9 @@
+/**
+ * Brevo History Import Route
+ *
+ * POST /api/admin/integrations/brevo/backfill - One chunk of the resumable
+ * history import (contacts upsert, then orders with historical:true so no
+ * automation fires). The integrations modal loops on the returned cursor.
+ */
+
+export { postBrevoBackfill as POST } from '@rovela-ai/sdk/admin/api'

package/templates/store-template/app/api/admin/integrations/brevo/route.ts

@@ -0,0 +1,9 @@
+/**
+ * Brevo Integration Status Route
+ *
+ * GET /api/admin/integrations/brevo - Live Brevo status for the
+ * integrations modal (account identity, sender verification, whether the
+ * eCommerce module already holds orders, current email transport).
+ */
+
+export { getBrevoStatus as GET } from '@rovela-ai/sdk/admin/api'

package/templates/store-template/next.config.js

@@ -50,7 +50,10 @@ const nextConfig = {
   // the SDK's core/config get the file, and every other function (checkout,
   // webhooks, auth, admin emails) silently falls back to default styling.
   outputFileTracingIncludes: {
-    '/**': ['./.rovela/blueprint.json'],
+    // nodemailer is loaded via a bundler-invisible require (the emails graph
+    // is client-reachable, a static import breaks the build) so the tracer
+    // can't see it — force-include it or the SMTP transport 500s on Vercel.
+    '/**': ['./.rovela/blueprint.json', './node_modules/nodemailer/**'],
   },
 
   // Image domains for Unsplash, CDNs, and R2 storage

package/templates/store-template/package.json

@@ -9,13 +9,14 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@rovela-ai/sdk": "0.22.0",
+    "@rovela-ai/sdk": "0.24.0",
     "@tailwindcss/forms": "0.5.11",
     "@tailwindcss/typography": "0.5.19",
     "autoprefixer": "10.4.24",
     "lucide-react": "0.555.0",
     "next": "16.2.10",
     "next-auth": "4.24.13",
+    "nodemailer": "7.0.13",
     "postcss": "8.5.6",
     "react": "19.2.4",
     "react-dom": "19.2.4",