@stacksjs/types 0.70.23 → 0.70.25

package/src/email.ts

@@ -1,4 +1,274 @@
-import type { I18n } from 'vue-email'
+/**
+ * i18n bag passed to STX email templates at render time. Stacks emails
+ * are STX, not vue-email — keys/values are user-defined per template.
+ * The shape is intentionally open: each template declares its own
+ * placeholders and the renderer interpolates them as-is.
+ */
+export interface I18n {
+  [key: string]: unknown
+}
+
+export interface AutoResponderConfig {
+  enabled: boolean
+  subject: string
+  body: string
+  schedule?: {
+    start?: string
+    end?: string
+  }
+}
+
+export interface EmailFilterRule {
+  field: 'from' | 'to' | 'subject' | 'body'
+  operator: 'contains' | 'equals' | 'startsWith' | 'endsWith' | 'regex'
+  value: string
+  action: 'move' | 'delete' | 'forward' | 'label'
+  actionValue?: string
+}
+
+export interface MailboxConfig {
+  /** Email address (preferred) - e.g., 'chris@stacksjs.com' */
+  email?: string
+  /** @deprecated Use 'email' instead */
+  address?: string
+  displayName?: string
+  /**
+   * Password for IMAP/SMTP authentication.
+   * If not provided, will be looked up from MAIL_PASSWORD_<USERNAME> env var.
+   * Passwords are stored in AWS Secrets Manager after first deploy.
+   */
+  password?: string
+  forwardTo?: string[]
+  autoResponder?: AutoResponderConfig
+  filters?: EmailFilterRule[]
+}
+
+export interface MailServerInstanceConfig {
+  /**
+   * EC2 instance type for the mail server
+   * @default 't4g.nano' for serverless, 't3.small' for server mode
+   */
+  type?: 't4g.nano' | 't4g.micro' | 't4g.small' | 't4g.medium' | 't3.nano' | 't3.micro' | 't3.small' | 't3.medium' | 't3.large' | 't3.xlarge'
+
+  /**
+   * Use spot instance for cost savings (~70% cheaper)
+   * Note: Spot instances can be interrupted with 2-minute warning
+   * @default false
+   */
+  spot?: boolean
+
+  /**
+   * Root volume size in GB
+   * @default 8 for serverless, 30 for server mode
+   */
+  diskSize?: number
+
+  /**
+   * SSH key pair name for instance access (optional)
+   */
+  keyPair?: string
+}
+
+export interface MailServerPortsConfig {
+  /**
+   * Standard SMTP port
+   * @default 25
+   */
+  smtp?: number
+
+  /**
+   * SMTP over TLS (implicit TLS)
+   * @default 465
+   */
+  smtps?: number
+
+  /**
+   * SMTP submission port (STARTTLS)
+   * @default 587
+   */
+  submission?: number
+
+  /**
+   * IMAP port (plaintext, not recommended)
+   * @default 143
+   */
+  imap?: number
+
+  /**
+   * IMAP over TLS
+   * @default 993
+   */
+  imaps?: number
+
+  /**
+   * POP3 port (plaintext, not recommended)
+   * @default 110
+   */
+  pop3?: number
+
+  /**
+   * POP3 over TLS
+   * @default 995
+   */
+  pop3s?: number
+
+  /**
+   * @deprecated Use 'submission' instead
+   */
+  smtpStartTls?: number
+}
+
+export interface MailServerFeaturesConfig {
+  /**
+   * Enable IMAP server
+   * @default true
+   */
+  imap?: boolean
+
+  /**
+   * Enable POP3 server
+   * @default true
+   */
+  pop3?: boolean
+
+  /**
+   * Enable webmail interface (future)
+   * @default false
+   */
+  webmail?: boolean
+
+  /**
+   * Enable CalDAV for calendar sync
+   * @default false
+   */
+  calDAV?: boolean
+
+  /**
+   * Enable CardDAV for contacts sync
+   * @default false
+   */
+  cardDAV?: boolean
+
+  /**
+   * Enable Exchange ActiveSync
+   * @default false
+   */
+  activeSync?: boolean
+}
+
+/**
+ * Email category types for automatic email categorization (Gmail-style)
+ */
+export type EmailCategory = 'social' | 'forums' | 'updates' | 'promotions' | 'primary'
+
+/**
+ * Patterns for matching emails to categories
+ */
+export interface CategoryPatterns {
+  /**
+   * Domain names to match (e.g., 'facebookmail.com', 'twitter.com')
+   * Matched against the sender's email domain
+   */
+  domains?: string[]
+
+  /**
+   * Substrings to match in the sender address (e.g., 'notification@', '@social.')
+   */
+  substrings?: string[]
+
+  /**
+   * Email headers to match (e.g., { 'list-id': [''], 'precedence': ['list', 'bulk'] })
+   * Empty string array means "header exists"
+   */
+  headers?: Record<string, string[]>
+}
+
+/**
+ * Configuration for automatic email categorization
+ */
+export interface EmailCategorizationConfig {
+  /**
+   * Enable automatic email categorization into Gmail-style folders
+   * @default true
+   */
+  enabled?: boolean
+
+  /**
+   * Social category patterns (Facebook, Twitter, LinkedIn, etc.)
+   */
+  social?: CategoryPatterns
+
+  /**
+   * Forums category patterns (mailing lists, Google Groups, etc.)
+   */
+  forums?: CategoryPatterns
+
+  /**
+   * Updates category patterns (GitHub, Stripe, shipping notifications, etc.)
+   */
+  updates?: CategoryPatterns
+
+  /**
+   * Promotions category patterns (marketing emails, newsletters, etc.)
+   */
+  promotions?: CategoryPatterns
+}
+
+export interface EmailServerConfig {
+  enabled: boolean
+  scan?: boolean // spam/virus scanning
+
+  /**
+   * Server mode:
+   * - 'server': Full-featured Zig mail server with IMAP, POP3, CalDAV, etc. (default)
+   * - 'serverless': Lightweight TypeScript/Bun server (~$3/month)
+   * @default 'server'
+   */
+  mode?: 'serverless' | 'server'
+
+  storage?: {
+    bucket?: string
+    retentionDays?: number
+    archiveAfterDays?: number
+  }
+  forwarding?: Record<string, string[]> // alias -> destinations
+  autoResponders?: AutoResponderConfig[]
+
+  /**
+   * Mail server instance configuration
+   * Controls the EC2 instance that runs IMAP/SMTP
+   */
+  instance?: MailServerInstanceConfig
+
+  /**
+   * Mail server ports configuration
+   */
+  ports?: MailServerPortsConfig
+
+  /**
+   * Mail server features (only available in 'server' mode)
+   */
+  features?: MailServerFeaturesConfig
+
+  /**
+   * Subdomain for the mail server
+   * @default 'mail'
+   * @example 'mail' -> mail.yourdomain.com
+   */
+  subdomain?: string
+
+  /**
+   * Automatic email categorization (Gmail-style folders)
+   * Categorizes incoming emails into Social, Forums, Updates, Promotions folders
+   */
+  categorization?: EmailCategorizationConfig
+}
+
+export interface EmailNotificationsConfig {
+  newEmail?: boolean
+  bounces?: boolean
+  complaints?: boolean
+}
 
 export interface EmailOptions {
   from: {
@@ -6,16 +276,16 @@ export interface EmailOptions {
     address: string
   }
 
-  mailboxes: string[]
+  mailboxes: string[] | MailboxConfig[]
+  domain?: string
 
   url: string
   charset: string
 
-  server: {
-    scan?: boolean
-  }
+  server: EmailServerConfig
+  notifications?: EmailNotificationsConfig
 
-  default: 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap'
+  default: 'log' | 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap' | 'smtp'
 }
 
 export type EmailConfig = Partial<EmailOptions>
@@ -29,14 +299,24 @@ export interface EmailResult {
   success: boolean
   provider: string
   messageId?: string
-  [key: string]: any
+  /** Additional metadata from the email provider */
+  metadata?: Record<string, unknown>
 }
 
 // Base configuration interface
 export interface EmailDriverConfig {
   maxRetries?: number
   retryTimeout?: number
-  [key: string]: any
+}
+
+/** Options for email template rendering */
+export interface EmailTemplateOptions {
+  /** Template variables to replace */
+  variables?: Record<string, string | number | boolean | undefined | null>
+  /** Layout to wrap the template in */
+  layout?: string | false
+  /** Subject line for the email */
+  subject?: string
 }
 
 // Email driver interface
@@ -45,15 +325,15 @@ export interface EmailDriver {
   name: string
 
   /** Send an email */
-  send: (message: EmailMessage, options?: RenderOptions) => Promise<EmailResult>
+  send: (message: EmailMessage, options?: EmailTemplateOptions) => Promise<EmailResult>
 
   /** Configure the driver */
   configure: (config: EmailDriverConfig) => void
 }
 
 export interface EmailMessage {
-  /** Required sender email address */
-  from: EmailAddress
+  /** Sender email address (optional, will use config default if not provided) */
+  from?: EmailAddress
   /** Primary recipient(s) */
   to: string | string[] | EmailAddress[]
   /** Carbon copy recipient(s) */
@@ -62,12 +342,22 @@ export interface EmailMessage {
   bcc?: string | string[] | EmailAddress[]
   /** Email subject line */
   subject: string
-  /** Path to email template or HTML content */
+  /** Path to email template (Vue component) */
   template?: string
-  /** Optional plain text fallback */
+  /** Direct HTML content for the email body */
+  html?: string
+  /** Plain text fallback (recommended for accessibility) */
   text?: string
   /** Optional attachments */
   attachments?: EmailAttachment[]
+  /**
+   * Extra raw headers to inject into the outgoing envelope.
+   * Used by the newsletter package for `List-Unsubscribe` /
+   * `List-Unsubscribe-Post` (RFC 8058). Drivers that don't yet wire
+   * this through silently ignore — it never affects transactional
+   * sends.
+   */
+  headers?: Record<string, string>
   /** Optional callback after successful delivery */
   onSuccess?: () => Promise<{ message: string }> | { message: string }
   /** Optional callback after failed delivery */

package/src/errors.ts

@@ -26,7 +26,6 @@ export interface ErrorOptions {
     'activeUrl': string
     'alpha': string
     'alphaNumeric': string
-    'minLength': string
     'maxLength': string
     'fixedLength': string
     'confirmed': string
@@ -86,13 +85,13 @@ export interface ErrorOptions {
 
     // record
     'record': string
-    'record.minLength': string
+    'record.min': string
     'record.maxLength': string
     'record.fixedLength': string
 
     // array
     'array': string
-    'array.minLength': string
+    'array.min': string
     'array.maxLength': string
     'array.fixedLength': string
     'notEmpty': string

package/src/events.ts

@@ -7,12 +7,12 @@
  *
  * @example To fire an event, you may use any of the following approaches:
  * ```ts
- * dispatch('user:registered', { name: 'Chris', email: 'chris@stacksjs.org' })
+ * dispatch('user:registered', { name: 'Chris', email: 'chris@stacksjs.com' })
  *
  * // alternatively, you may use the following:
- * useEvent('user:registered', { name: 'Chris', email: 'chris@stacksjs.org' })
- * events.emit('user:registered', { name: 'Chris', email: 'chris@stacksjs.org' })
- * useEvents.emit('user:registered', { name: 'Chris', email: 'chris@stacksjs.org' })
+ * useEvent('user:registered', { name: 'Chris', email: 'chris@stacksjs.com' })
+ * events.emit('user:registered', { name: 'Chris', email: 'chris@stacksjs.com' })
+ * useEvents.emit('user:registered', { name: 'Chris', email: 'chris@stacksjs.com' })
  * ```
  *
  * @example To capture an event, you may use any of the following approaches:
@@ -29,4 +29,9 @@ export interface Events {
   [key: string]: string[]
 }
 
-export * from '../../../types/events'
+// `storage/framework/types/events.ts` is a project-generated declaration
+// (one entry per model: `'<name>:created' | '<name>:updated' | …`). Use
+// `export type *` so Bun erases the import at runtime — the file lives in
+// the consumer project, not in the published `@stacksjs/types` package, so
+// a value-level `export *` would fail to resolve once the package ships.
+export type * from '../../../types/events'

package/src/git.ts

@@ -28,7 +28,7 @@ export interface GitOptions {
    *
    * The git commit scopes to use.
    *
-   * @see https://stacksjs.org/docs/git/scopes
+   * @see https://stacksjs.com/docs/git/scopes
    * @example
    * git: [
    *   scopes: [
@@ -46,7 +46,7 @@ export interface GitOptions {
    * The git commit types to use.
    *
    * @default array
-   * @see https://stacksjs.org/docs/git/types
+   * @see https://stacksjs.com/docs/git/types
    * @see https://www.conventionalcommits.org/en/v1.0.0/
    * @example
    * ```ts
@@ -81,7 +81,7 @@ export interface GitOptions {
    *   confirmCommit: 'Are you sure you want to proceed with the commit above?',
    * }
    * ```
-   * @see https://stacksjs.org/docs/git/messages
+   * @see https://stacksjs.com/docs/git/messages
    */
   messages: {
     type: string

package/src/hashing.ts

@@ -9,7 +9,7 @@
  * longer it takes malicious users to generate "rainbow tables" of all possible string hash
  * values that may be used in brute force attacks against applications.
  *
- * @see https://stacksjs.org/docs/hashing
+ * @see https://stacksjs.com/docs/hashing
  */
 export interface HashingOptions {
   /**
@@ -19,7 +19,7 @@ export interface HashingOptions {
    * passwords for your application. By default, the bcrypt algorithm is
    * used; however, you remain free to modify this option if you wish.
    *
-   * @see https://stacksjs.org/docs/hashing
+   * @see https://stacksjs.com/docs/hashing
    */
   driver: 'argon2' | 'argon2id' | 'argon2i' | 'argon2d' | 'bcrypt'
 
@@ -30,7 +30,7 @@ export interface HashingOptions {
    * passwords are hashed using the Bcrypt algorithm. This will allow you
    * to control the amount of time it takes to hash the given password.
    *
-   * @see https://stacksjs.org/docs/hashing
+   * @see https://stacksjs.com/docs/hashing
    */
   bcrypt?: BcryptOptions
 
@@ -41,7 +41,7 @@ export interface HashingOptions {
    * passwords are hashed using the Argon algorithm. These will allow you
    * to control the amount of time it takes to hash the given password.
    *
-   * @see https://stacksjs.org/docs/hashing
+   * @see https://stacksjs.com/docs/hashing
    */
   argon2?: ArgonOptions
 }
@@ -55,23 +55,19 @@ export type HashingConfig = Partial<HashingOptions>
  * passwords are hashed using the Bcrypt algorithm. This will allow you
  * to control the amount of time it takes to hash the given password.
  *
- * @see https://stacksjs.org/docs/hashing
+ * @see https://stacksjs.com/docs/hashing
  */
 export interface BcryptOptions {
   /**
-   * Bcrypt salt rounds.
+   * Bcrypt rounds (cost factor).
+   * This is a number between 4-31.
+   * Higher values = more secure but slower.
+   * Laravel default: 10-12
    *
-   * @default number 10
-   * @see https://stacksjs.org/docs/hashing
+   * @default 12
+   * @see https://stacksjs.com/docs/hashing
    */
   rounds: number
-
-  /**
-   * Bcrypt cost. This is a number between 4-31.
-   * @default number 4
-   * @see https://stacksjs.org/docs/hashing
-   */
-  cost: number
 }
 
 /**
@@ -81,7 +77,7 @@ export interface BcryptOptions {
  * passwords are hashed using the Argon algorithm. These will allow you
  * to control the amount of time it takes to hash the given password.
  *
- * @see https://stacksjs.org/docs/hashing
+ * @see https://stacksjs.com/docs/hashing
  */
 export interface ArgonOptions {
   /**
@@ -90,7 +86,7 @@ export interface ArgonOptions {
    * Amount of memory (in kibibytes) to use.
    *
    * @default number 65536
-   * @see https://stacksjs.org/docs/hashing
+   * @see https://stacksjs.com/docs/hashing
    */
   memory?: number
 
@@ -100,7 +96,7 @@ export interface ArgonOptions {
   //  * Degree of parallelism (i.e. number of threads).
   //  *
   //  * @default number 1
-  //  * @see https://stacksjs.org/docs/hashing
+  //  * @see https://stacksjs.com/docs/hashing
   //  */
   // threads?: number
 
@@ -110,7 +106,7 @@ export interface ArgonOptions {
    * Execution time.
    *
    * @default number 1
-   * @see https://stacksjs.org/docs/hashing
+   * @see https://stacksjs.com/docs/hashing
    */
   time?: number
 }

package/src/i18n.ts

@@ -1,3 +1,6 @@
+/**
+ * Vite plugin options for Vue I18n
+ */
 interface VitePluginVueI18nOptions {
   forceStringify?: boolean
   runtimeOnly?: boolean
@@ -9,11 +12,110 @@ interface VitePluginVueI18nOptions {
   useVueI18nImportName?: boolean
 }
 
+/**
+ * Translation messages - can be nested objects or strings
+ */
+export type TranslationMessages = {
+  [key: string]: string | TranslationMessages
+}
+
+/**
+ * All translations keyed by locale
+ */
+export type Translations = {
+  [locale: string]: TranslationMessages
+}
+
+/**
+ * Date/time format configurations per locale
+ */
+export type DateTimeFormats = {
+  [locale: string]: {
+    [formatName: string]: Intl.DateTimeFormatOptions
+  }
+}
+
+/**
+ * Number format configurations per locale
+ */
+export type NumberFormats = {
+  [locale: string]: {
+    [formatName: string]: Intl.NumberFormatOptions
+  }
+}
+
 /**
  * **Internationalization Options**
  *
- * The i18n option.
- *
- * @see https://github.com/intlify/bundle-tools/blob/main/packages/vite-plugin-vue-i18n/src/options.ts
+ * Configuration for the i18n system.
+ */
+export interface I18nOptions {
+  /**
+   * Default locale
+   * @default 'en'
+   */
+  locale: string
+
+  /**
+   * Fallback locale when translation is not found
+   * @default 'en'
+   */
+  fallbackLocale: string
+
+  /**
+   * Available locales
+   */
+  availableLocales?: string[]
+
+  /**
+   * Directory containing translation files
+   * @default 'lang'
+   */
+  langDir?: string
+
+  /**
+   * Initial translations
+   */
+  messages?: Translations
+
+  /**
+   * Whether to warn about missing translations in development
+   * @default true
+   */
+  warnMissing?: boolean
+
+  /**
+   * Separator for nested keys
+   * @default '.'
+   */
+  keySeparator?: string
+
+  /**
+   * Plural separator
+   * @default '|'
+   */
+  pluralSeparator?: string
+
+  /**
+   * Date/time formatting options
+   */
+  dateTimeFormats?: DateTimeFormats
+
+  /**
+   * Number formatting options
+   */
+  numberFormats?: NumberFormats
+
+  /**
+   * Vite plugin options
+   */
+  vite?: VitePluginVueI18nOptions
+}
+
+export type I18nConfig = Partial<I18nOptions>
+
+/**
+ * Legacy alias
+ * @deprecated Use I18nOptions instead
  */
 export type i18nOptions = VitePluginVueI18nOptions