@nextsparkjs/core 0.1.0-beta.149 → 0.1.0-beta.150

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/core",
-  "version": "0.1.0-beta.149",
+  "version": "0.1.0-beta.150",
   "description": "NextSpark - The complete SaaS framework for Next.js",
   "license": "MIT",
   "author": "NextSpark <hello@nextspark.dev>",
@@ -188,6 +188,10 @@
       "types": "./dist/lib/*.d.ts",
       "import": "./dist/lib/*.js"
     },
+    "./emails/*": {
+      "types": "./dist/emails/*.d.ts",
+      "import": "./dist/emails/*.js"
+    },
     "./hooks": {
       "types": "./dist/hooks/index.d.ts",
       "import": "./dist/hooks/index.js"
@@ -463,7 +467,7 @@
     "tailwind-merge": "^3.3.1",
     "uuid": "^13.0.0",
     "zod": "^4.1.5",
-    "@nextsparkjs/testing": "0.1.0-beta.149"
+    "@nextsparkjs/testing": "0.1.0-beta.150"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs || true",

package/scripts/build/registry/discovery/emails.mjs

@@ -0,0 +1,146 @@
+/**
+ * Email Discovery
+ *
+ * Discovers email template files from core defaults and the active theme.
+ * Theme files override core defaults at the same slug; new theme slugs are
+ * additive (themes can ship templates that core doesn't know about).
+ *
+ * @module core/scripts/build/registry/discovery/emails
+ */
+
+import { readdir } from 'fs/promises'
+import { join } from 'path'
+
+import { CONFIG as DEFAULT_CONFIG } from '../config.mjs'
+import { log, verbose } from '../../../utils/index.mjs'
+
+/**
+ * @typedef {Object} DiscoveredEmail
+ * @property {string} slug             - Filename without extension (e.g. 'verify-email')
+ * @property {'core' | 'theme'} source - Where the file lives
+ * @property {string} importPath       - Module specifier the generator will emit
+ * @property {string} importName       - Sanitized identifier safe to use in generated TS
+ */
+
+/**
+ * Convert a file slug to a JavaScript identifier safe for use as an import name.
+ * - "verify-email"  → "verifyEmail"
+ * - "team-invite"   → "teamInvite"
+ * - "purchase.v2"   → "purchaseV2"
+ *
+ * Keeps existing camelCase intact (e.g. "verifyEmail" → "verifyEmail").
+ *
+ * @param {string} slug
+ * @returns {string}
+ */
+function slugToIdentifier(slug) {
+  return slug
+    .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^([0-9])/, '_$1')
+}
+
+/**
+ * Walk a directory and return its email entries (one per .ts/.tsx file at the
+ * top level — emails are not nested).
+ *
+ * @param {string} dir
+ * @returns {Promise<Array<{ slug: string, fileName: string }>>}
+ */
+async function listEmailFiles(dir) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    // Directory doesn't exist — that's fine, no emails here.
+    return []
+  }
+
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.tsx')) continue
+    // Skip barrel files and underscore-prefixed (README/notes)
+    if (entry.name === 'index.ts' || entry.name === 'index.tsx') continue
+    if (entry.name.startsWith('_')) continue
+    if (entry.name.endsWith('.d.ts')) continue
+    if (entry.name.endsWith('.test.ts') || entry.name.endsWith('.test.tsx')) continue
+
+    const slug = entry.name.replace(/\.(tsx|ts)$/, '')
+    out.push({ slug, fileName: entry.name })
+  }
+  return out
+}
+
+/**
+ * Discover all email templates: core defaults first, then active theme overrides
+ * and additions. Theme entries take precedence per slug.
+ *
+ * @param {object} config - Configuration object from getConfig() (defaults to DEFAULT_CONFIG)
+ * @returns {Promise<DiscoveredEmail[]>}
+ */
+export async function discoverEmails(config = DEFAULT_CONFIG) {
+  log('Discovering email templates...', 'info')
+
+  // Resolve core default emails dir.
+  // - Monorepo mode: packages/core/src/emails/    (uncompiled .ts)
+  // - NPM mode: node_modules/@nextsparkjs/core/dist/emails/ (compiled .js)
+  // The build-time import alias is the same shape in both cases — Next.js
+  // resolves '@nextsparkjs/core/emails/<slug>' via the package's exports field
+  // in npm mode, and '@/core/emails/<slug>' via tsconfig paths in monorepo mode.
+  const coreEmailsDir = config.isNpmMode
+    ? join(config.coreDir, 'dist', 'emails')
+    : join(config.coreDir, 'src', 'emails')
+
+  const coreImportBase = config.isNpmMode
+    ? '@nextsparkjs/core/emails'
+    : '@/core/emails'
+
+  /** @type {Map<string, DiscoveredEmail>} */
+  const merged = new Map()
+
+  // Core defaults
+  const coreFiles = await listEmailFiles(coreEmailsDir)
+  if (coreFiles.length > 0) {
+    verbose(`Found ${coreFiles.length} core email template(s) in: ${coreEmailsDir}`)
+    for (const { slug } of coreFiles) {
+      merged.set(slug, {
+        slug,
+        source: 'core',
+        importPath: `${coreImportBase}/${slug}`,
+        importName: `${slugToIdentifier(slug)}_core`,
+      })
+    }
+  } else {
+    verbose(`No core email templates found in: ${coreEmailsDir}`)
+  }
+
+  // Theme overrides + additions.
+  if (config.activeTheme && config.themesDir) {
+    const themeEmailsDir = join(config.themesDir, config.activeTheme, 'emails')
+    const themeFiles = await listEmailFiles(themeEmailsDir)
+
+    if (themeFiles.length > 0) {
+      verbose(`Found ${themeFiles.length} theme email override(s) in: ${themeEmailsDir}`)
+      for (const { slug } of themeFiles) {
+        merged.set(slug, {
+          slug,
+          source: 'theme',
+          importPath: `@/contents/themes/${config.activeTheme}/emails/${slug}`,
+          importName: `${slugToIdentifier(slug)}_theme`,
+        })
+      }
+    }
+  } else if (!config.activeTheme) {
+    verbose('No active theme — only core email templates will be registered.')
+  }
+
+  const result = Array.from(merged.values()).sort((a, b) => a.slug.localeCompare(b.slug))
+
+  log(
+    `Discovered ${result.length} email template(s): ` +
+      result.map(e => `${e.slug}(${e.source})`).join(', '),
+    'info',
+  )
+
+  return result
+}

package/scripts/build/registry/generators/email-registry.mjs

@@ -0,0 +1,94 @@
+/**
+ * Email Registry Generator
+ *
+ * Generates email-registry.ts — a static, frozen map from slug to template
+ * function, where theme overrides win over core defaults.
+ *
+ * The generated file is intentionally NOT annotated with `Record<string, …>`.
+ * Instead it uses `as const` so TypeScript infers per-slug types from each
+ * imported function's signature — same trick `entity-registry.mjs` already
+ * uses. This means consumer-defined slugs (in `themes/<theme>/emails/`) get
+ * full per-slug type inference for free, with zero `declare module` boilerplate.
+ *
+ * @module core/scripts/build/registry/generators/email-registry
+ */
+
+import { join } from 'path'
+import { convertCorePath } from '../config.mjs'
+
+/**
+ * @param {Array<{slug: string, source: 'core'|'theme', importPath: string, importName: string}>} emails
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {string} Generated TypeScript content
+ */
+export function generateEmailRegistry(emails, config) {
+  const outputFilePath = join(config.outputDir, 'email-registry.ts')
+
+  // Resolve core import paths through convertCorePath so they work in both
+  // monorepo and npm modes. Theme paths are project-local so don't need it.
+  const importLines = emails
+    .map(email => {
+      const importPath =
+        email.source === 'core'
+          ? convertCorePath(email.importPath, outputFilePath, config)
+          : email.importPath
+      return `import ${email.importName} from '${importPath}'`
+    })
+    .join('\n')
+
+  // Map literal entries — quoted slug keys (some slugs are kebab-case which
+  // is not a valid identifier without quoting).
+  const registryEntries = emails
+    .map(email => `  '${email.slug}': ${email.importName},`)
+    .join('\n')
+
+  // Metadata for diagnostics / DX
+  const metadataEntries = emails
+    .map(
+      email =>
+        `  '${email.slug}': { source: '${email.source}' as const, overridden: ${email.source === 'theme'} },`,
+    )
+    .join('\n')
+
+  const generatedAt = new Date().toISOString()
+  const sourcesLine = emails.length === 0
+    ? '(no email templates discovered)'
+    : emails.map(e => `${e.slug}(${e.source})`).join(', ')
+
+  return `/**
+ * Auto-generated Email Registry
+ *
+ * Generated at: ${generatedAt}
+ * Templates discovered: ${emails.length}
+ * Sources: ${sourcesLine}
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build/registry.mjs.
+ * Override behaviour: drop a file at \`themes/<active-theme>/emails/<slug>.ts\`
+ * and rebuild — the theme version wins over the core default at the same slug,
+ * and entirely new slugs from a theme are additive.
+ *
+ * Type safety: this file emits a literal object with \`as const\` so TypeScript
+ * infers per-slug data types from each imported function's signature.
+ * Do NOT add a \`Record<string, …>\` annotation — that would erase the per-slug
+ * inference and consumer-defined slugs would lose type safety.
+ */
+
+${importLines}
+
+export const EMAIL_REGISTRY = {
+${registryEntries}
+} as const
+
+export type EmailSlug = keyof typeof EMAIL_REGISTRY
+
+export const EMAIL_REGISTRY_METADATA = {
+${metadataEntries}
+} as const
+
+export const EMAIL_REGISTRY_INFO = {
+  totalTemplates: ${emails.length},
+  generatedAt: '${generatedAt}',
+  slugs: [${emails.map(e => `'${e.slug}'`).join(', ')}] as const,
+} as const
+`
+}

package/scripts/build/registry.mjs

@@ -51,6 +51,7 @@ import { discoverPlugins } from './registry/discovery/plugins.mjs'
 import { discoverThemes } from './registry/discovery/themes.mjs'
 import { discoverMiddlewares } from './registry/discovery/middlewares.mjs'
 import { discoverTemplates } from './registry/discovery/templates.mjs'
+import { discoverEmails } from './registry/discovery/emails.mjs'
 import { discoverBlocks } from './registry/discovery/blocks.mjs'
 import { discoverCoreRoutes } from './registry/discovery/core-routes.mjs'
 import { discoverApiPresets } from './registry/discovery/api-presets.mjs'
@@ -60,6 +61,7 @@ import { generateEntityRegistry, generateEntityRegistryClient } from './registry
 import { generateEntityTypes } from './registry/generators/entity-types.mjs'
 import { generateThemeRegistry } from './registry/generators/theme-registry.mjs'
 import { generateTemplateRegistry, generateTemplateRegistryClient } from './registry/generators/template-registry.mjs'
+import { generateEmailRegistry } from './registry/generators/email-registry.mjs'
 import { generateBlockRegistry } from './registry/generators/block-registry.mjs'
 import { generateMiddlewareRegistry } from './registry/generators/middleware-registry.mjs'
 import { generateRouteHandlersRegistry } from './registry/generators/route-handlers.mjs'
@@ -87,7 +89,7 @@ import { syncAppGlobalsCss } from './theme.mjs'
 
 // ==================== Registry File Generation ====================
 
-async function generateRegistryFiles(CONFIG, plugins, entities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData) {
+async function generateRegistryFiles(CONFIG, plugins, entities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails) {
   log('Generating registry files...', 'build')
 
   try {
@@ -109,6 +111,7 @@ async function generateRegistryFiles(CONFIG, plugins, entities, themes, template
       { name: 'translation-registry.ts', content: generateTranslationRegistry(themes, CONFIG) },
       { name: 'template-registry.ts', content: generateTemplateRegistry(templates, CONFIG) },
       { name: 'template-registry.client.ts', content: templateRegistryClientContent },
+      { name: 'email-registry.ts', content: generateEmailRegistry(emails, CONFIG) },
       { name: 'block-registry.ts', content: generateBlockRegistry(blocks, CONFIG) },
       { name: 'billing-registry.ts', content: await generateBillingRegistry(CONFIG.activeTheme, CONFIG.contentsDir, CONFIG) },
       { name: 'middleware-registry.ts', content: generateMiddlewareRegistry(middlewares, CONFIG) },
@@ -188,7 +191,7 @@ export async function buildRegistries(projectRoot = null) {
     await discoverParentChildRelations(CONFIG)
 
     // Discover all content types in parallel (pass CONFIG to each)
-    const [plugins, coreEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData] = await Promise.all([
+    const [plugins, coreEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails] = await Promise.all([
       discoverPlugins(CONFIG),
       discoverCoreEntities(CONFIG),
       discoverThemes(CONFIG),
@@ -197,7 +200,8 @@ export async function buildRegistries(projectRoot = null) {
       discoverBlocks(CONFIG),
       discoverPermissionsConfig(CONFIG),
       discoverCoreRoutes(CONFIG),
-      discoverApiPresets(CONFIG)
+      discoverApiPresets(CONFIG),
+      discoverEmails(CONFIG)
     ])
 
     // Aggregate all entities with proper priority: plugin < core < theme
@@ -256,7 +260,7 @@ export async function buildRegistries(projectRoot = null) {
 
     // Hoist plugin dependencies to root workspace for proper resolution
     // Generate all registry files (use aggregated entities for entity registry + blocks)
-    await generateRegistryFiles(CONFIG, plugins, allEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData)
+    await generateRegistryFiles(CONFIG, plugins, allEntities, themes, templates, middlewares, blocks, permissionsConfig, coreRoutes, apiPresetsData, emails)
 
     // Generate missing pages for templates that don't have core app pages
     await generateMissingPages(templates, CONFIG)

package/templates/app/api/v1/teams/[teamId]/members/route.ts

@@ -16,7 +16,8 @@ import { inviteMemberSchema, memberListQuerySchema } from '@nextsparkjs/core/lib
 import { TeamMemberService, MembershipService } from '@nextsparkjs/core/lib/services'
 import type { TeamMember, TeamInvitation, TeamRole, Team } from '@nextsparkjs/core/lib/teams/types'
 import { EmailFactory } from '@nextsparkjs/core/lib/email/factory'
-import { createTeamInvitationEmail } from '@nextsparkjs/core/lib/email/templates'
+import { sendTeamInvitationEmail } from '@nextsparkjs/core/lib/email/send'
+import { I18N_CONFIG } from '@nextsparkjs/core/lib/config'
 
 // Role hierarchy for invite validation (higher number = more power)
 const ROLE_HIERARCHY: Record<TeamRole, number> = {
@@ -310,14 +311,15 @@ export const POST = withRateLimitTier(withApiLogging(
       try {
         const emailProvider = EmailFactory.getInstance()
         const inviterName = authResult.user!.email // Use email as inviter name
-        const emailContent = createTeamInvitationEmail(
-          validatedData.email,
+        const emailContent = await sendTeamInvitationEmail({
+          inviteeEmail: validatedData.email,
           inviterName,
-          team.name,
-          validatedData.role,
+          teamName: team.name,
+          role: validatedData.role,
           acceptUrl,
-          '7 days'
-        )
+          expiresIn: '7 days',
+          appName: process.env.NEXT_PUBLIC_APP_NAME || 'Your App',
+        }, I18N_CONFIG.defaultLocale)
 
         await emailProvider.send({
           to: validatedData.email,

package/templates/contents/themes/starter/emails/_README.md

@@ -0,0 +1,69 @@
+# Email templates
+
+Drop a `.ts` file in this directory to override or add transactional email
+templates for this theme. The build-time email registry picks files here
+over the core defaults at the same slug, and any new slugs are additive.
+
+## How discovery works
+
+At build time, `pnpm dev` and `pnpm build` regenerate
+`.nextspark/registries/email-registry.ts`. The registry first scans core's
+defaults, then walks `themes/<NEXT_PUBLIC_ACTIVE_THEME>/emails/`. Theme files
+with the same filename as a core default override the core file. Theme files
+with new filenames are added to the registry as new slugs.
+
+## File contract
+
+Each file must have a default export with this shape:
+
+```ts
+export default async function <name>(
+  data: <YourDataShape>,
+  locale?: string,
+): Promise<{ subject: string; html: string }>
+```
+
+`locale` is the BCP47 code (e.g. `'en'`, `'es'`); use it with
+`getTranslations({ locale, namespace: 'email.<slug>' })` from `next-intl/server`
+when you want translated copy. Core's defaults already do this for the four
+slugs below.
+
+## Core slugs you can override
+
+| Slug                | Data type                  | Sent on                                   |
+|---------------------|----------------------------|-------------------------------------------|
+| `verify-email`      | `VerificationEmailData`    | Email/password signup (when enabled)      |
+| `reset-password`    | `PasswordResetEmailData`   | Password reset request                    |
+| `otp-verification`  | `OtpVerificationEmailData` | OTP-based sign-in / verification          |
+| `team-invitation`   | `TeamInvitationEmailData`  | Adding a member to a team                 |
+
+Import the data types from `@nextsparkjs/core/lib/email/types`.
+
+## Adding new slugs
+
+A theme can ship slugs core doesn't know about (e.g. `welcome.ts`,
+`weekly-digest.ts`, `purchase-confirmation.ts`). After rebuild, they become
+available as `EMAIL_REGISTRY['<slug>']` from
+`@nextsparkjs/registries/email-registry` with full per-slug TypeScript
+inference of the data argument — no `declare module` boilerplate.
+
+## Falling back to core defaults
+
+Delete a file from this directory to revert that slug to core's default on
+the next build.
+
+## Convenience helpers for the four core slugs
+
+If you don't override, call sites in your project can keep using the typed
+helpers exposed by core:
+
+```ts
+import {
+  sendVerifyEmail,
+  sendResetPasswordEmail,
+  sendOtpVerificationEmail,
+  sendTeamInvitationEmail,
+} from '@nextsparkjs/core/lib/email/send'
+```
+
+These wrap `EMAIL_REGISTRY['<slug>']` and pick up your overrides automatically.

package/templates/contents/themes/starter/emails/verify-email.ts

@@ -0,0 +1,34 @@
+/**
+ * Theme override: Verify Email.
+ *
+ * Drop your branded HTML and copy here to customize the verification email.
+ * The build-time email registry in `@nextsparkjs/registries/email-registry`
+ * will pick this file over the core default at the same slug.
+ *
+ * The other three core slugs you can override or add to:
+ *   - reset-password.ts
+ *   - otp-verification.ts
+ *   - team-invitation.ts
+ *
+ * You can also add brand-new slugs here (e.g. `welcome.ts`,
+ * `purchase-confirmation.ts`). They're picked up automatically by the
+ * registry generator and become available as `EMAIL_REGISTRY['<slug>']` —
+ * with full per-slug TypeScript inference of the data argument.
+ *
+ * Out of the box this file simply delegates to core so the project keeps
+ * working before you brand it. Replace the body with your own HTML when
+ * you're ready, or delete this file entirely to fall back to the core default.
+ */
+
+import coreVerifyEmail from '@nextsparkjs/core/emails/verify-email'
+import type {
+  EmailContent,
+  VerificationEmailData,
+} from '@nextsparkjs/core/lib/email/types'
+
+export default async function verifyEmail(
+  data: VerificationEmailData,
+  locale?: string,
+): Promise<EmailContent> {
+  return coreVerifyEmail(data, locale)
+}

package/tests/jest/__mocks__/@nextsparkjs/registries/email-registry.ts

@@ -0,0 +1,41 @@
+/**
+ * Test mock for `@nextsparkjs/registries/email-registry`.
+ *
+ * Mirrors what the build-time generator (`generators/email-registry.mjs`)
+ * emits in production, but constructed by hand so unit tests don't depend
+ * on running the real registry build before each test run. Imports the
+ * actual core default templates so end-to-end tests for
+ * `lib/email/send` and the deprecated `lib/email/templates` adapters
+ * exercise real output.
+ *
+ * Tests that need to spy on the registry should use `jest.mock(
+ * '@nextsparkjs/registries/email-registry', ...)` to fully replace this
+ * module — that takes precedence over the file mapping.
+ */
+
+import verifyEmail from '../../../../../src/emails/verify-email'
+import resetPassword from '../../../../../src/emails/reset-password'
+import otpVerification from '../../../../../src/emails/otp-verification'
+import teamInvitation from '../../../../../src/emails/team-invitation'
+
+export const EMAIL_REGISTRY = {
+  'verify-email': verifyEmail,
+  'reset-password': resetPassword,
+  'otp-verification': otpVerification,
+  'team-invitation': teamInvitation,
+} as const
+
+export type EmailSlug = keyof typeof EMAIL_REGISTRY
+
+export const EMAIL_REGISTRY_METADATA = {
+  'verify-email': { source: 'core' as const, overridden: false },
+  'reset-password': { source: 'core' as const, overridden: false },
+  'otp-verification': { source: 'core' as const, overridden: false },
+  'team-invitation': { source: 'core' as const, overridden: false },
+} as const
+
+export const EMAIL_REGISTRY_INFO = {
+  totalTemplates: 4,
+  generatedAt: 'test-mock',
+  slugs: ['verify-email', 'reset-password', 'otp-verification', 'team-invitation'] as const,
+} as const

package/tests/jest/__mocks__/next-intl-server.js

@@ -0,0 +1,55 @@
+/**
+ * Jest mock for `next-intl/server`'s `getTranslations`.
+ *
+ * Loads the corresponding `messages/<locale>/<root>.json` file directly and
+ * resolves keys inside `namespace` (which can be dotted, e.g. `email.verifyEmail`).
+ * Supports ICU-style `{var}` placeholders in values — replaced naively, no
+ * pluralization. Sufficient for email template snapshot tests.
+ */
+
+const path = require('path')
+const fs = require('fs')
+
+function loadNamespace(locale, namespace) {
+  // namespace is dotted: "email.verifyEmail" → root file "email", key path "verifyEmail"
+  const [rootFile, ...rest] = namespace.split('.')
+  const filePath = path.join(
+    __dirname,
+    '../../../src/messages',
+    locale,
+    `${rootFile}.json`,
+  )
+  const raw = fs.readFileSync(filePath, 'utf8')
+  let obj = JSON.parse(raw)
+  for (const segment of rest) {
+    obj = obj[segment]
+    if (!obj) throw new Error(`next-intl mock: missing segment "${segment}" in ${filePath}`)
+  }
+  return obj
+}
+
+function format(template, params) {
+  if (!params) return template
+  return template.replace(/\{(\w+)\}/g, (_, key) =>
+    params[key] === undefined ? `{${key}}` : String(params[key]),
+  )
+}
+
+async function getTranslations(opts) {
+  const locale = opts?.locale || 'en'
+  const namespace = opts?.namespace || ''
+  const ns = loadNamespace(locale, namespace)
+
+  return function t(key, params) {
+    const value = ns[key]
+    if (value === undefined) {
+      throw new Error(`next-intl mock: missing key "${key}" in namespace "${namespace}"`)
+    }
+    return format(value, params)
+  }
+}
+
+module.exports = {
+  getTranslations,
+  __esModule: true,
+}