@stacksjs/types 0.70.44 → 0.70.53

package/src/dashboard.ts

@@ -12,6 +12,14 @@
  * row when there's no newsletter without losing the model viewer.
  */
 export interface DashboardOptions {
+  /**
+   * Top-level feature gate. When `false`, the entire admin SPA + dashboard
+   * routes stay un-registered at boot. Missing or `true` keeps the dashboard
+   * on — the framework default, since every Stacks app wants it.
+   */
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
   /** Per-section visibility toggles. Omit a section to leave it enabled. */
   sections?: {
     library?: { enabled?: boolean }
@@ -35,6 +43,176 @@ export interface DashboardOptions {
       allModels?: { enabled?: boolean }
     }
   }
+  /**
+   * CI tracking surface — GitHub Actions health across the configured orgs.
+   * Ports the standalone `repo-dashboard` app into the dashboard
+   * (stacksjs/stacks#1844). Defaults to off because most projects don't
+   * own multiple GitHub orgs; opt in by listing orgs and surfacing a
+   * `GITHUB_TOKEN` in the environment.
+   */
+  ci?: {
+    enabled?: boolean
+    /** Orgs whose repos appear as per-tab CI cards. */
+    orgs?: string[]
+    /** Self-hosted runner caps per org. Defaults to {@link runnerCapDefault}. */
+    runnerCaps?: Record<string, number>
+    /** Fallback cap for orgs missing from `runnerCaps`. Defaults to 20. */
+    runnerCapDefault?: number
+    /** Repo names to exclude from the CI feed. */
+    ignoreRepos?: string[]
+    /**
+     * Failing-CI notification fan-out (stacksjs/stacks#1849).
+     *
+     * When enabled, the dashboard fires a notification through the
+     * configured channels every time a repo's CI transitions from
+     * success → failure (or first-time-seen → failure). Sticky-red
+     * repos don't keep firing; same-run-id polls don't re-fire; a
+     * 5-minute cooldown silences flap-storms.
+     */
+    notifications?: {
+      enabled?: boolean
+      /**
+       * Channels to fan out through. Maps to the same values
+       * `notify()` from @stacksjs/notifications accepts. Defaults to
+       * `['chat']` — Slack via webhook — because that channel
+       * doesn't need a recipient list (it's already scoped to a
+       * Slack channel via env).
+       */
+      channels?: Array<'email' | 'sms' | 'chat' | 'database'>
+      /**
+       * Per-channel recipients for the channels that need one
+       * (email/sms/database). Skipped for `chat`. Each entry must
+       * carry the field the named channel requires (`email`,
+       * `phone`, `userId`).
+       */
+      recipients?: Array<{ email?: string, phone?: string, userId?: number }>
+      /**
+       * Minimum delay (minutes) between consecutive notifications for
+       * the same repo. Defaults to 5. Set to 0 to disable.
+       */
+      cooldownMinutes?: number
+    }
+    /**
+     * Runner-pressure alerts (stacksjs/stacks#1850).
+     *
+     * When an org's queued-job count stays at or above
+     * `queuedThreshold` for `windowMinutes`, the dashboard fires a
+     * notification through the configured channels. Hysteresis: an
+     * already-alerting org doesn't re-fire until the queue drops
+     * below threshold for a full window first.
+     */
+    alerts?: {
+      enabled?: boolean
+      /** Queue depth at or above counts as pressure. Defaults to 8. */
+      queuedThreshold?: number
+      /** Duration the threshold must hold in either direction before
+       *  the alert fires / clears. Defaults to 10 minutes. */
+      windowMinutes?: number
+      /** Same channel options as {@link notifications.channels}. */
+      channels?: Array<'email' | 'sms' | 'chat' | 'database'>
+      /** Same recipient shape as {@link notifications.recipients}. */
+      recipients?: Array<{ email?: string, phone?: string, userId?: number }>
+      /**
+       * How long the runner-sample time-series is kept on disk.
+       * Older samples are pruned during each refresh to bound
+       * storage. Defaults to 24h.
+       */
+      retentionHours?: number
+    }
+  }
 }
 
 export type DashboardConfig = Partial<DashboardOptions>
+
+/**
+ * Per-model dashboard configuration (stacksjs/stacks#1843).
+ *
+ * Attach to a model definition to influence how the model surfaces in the
+ * dashboard sidebar without touching the framework's dashboard internals:
+ *
+ * ```ts
+ * defineModel({
+ *   name: 'AuditLog',
+ *   table: 'audit_logs',
+ *   dashboard: {
+ *     section: 'management',
+ *     icon: 'shield',
+ *     roles: ['admin'],
+ *     description: 'Append-only audit trail (admin-only)',
+ *   },
+ *   attributes: { … },
+ * })
+ * ```
+ *
+ * Resolution chain (most specific → fallback):
+ *
+ *   1. `dashboard.enabled === false` → model is hidden from the sidebar
+ *      entirely. The dynamic ORM viewer (`/models/<id>`) still works for
+ *      direct navigation, but the row is suppressed.
+ *   2. `dashboard.section` → pins the model to that section, overriding
+ *      the path-based auto-categorisation (commerce/, Content/, etc.).
+ *   3. `dashboard.label` / `dashboard.icon` → display overrides; fall back
+ *      to the model name and `iconMap` lookup.
+ *   4. `dashboard.roles` → role-gates the sidebar row. The server-side
+ *      sidebar builder emits the row with role metadata; the client filters
+ *      it out for users who lack a matching role. Permissive default
+ *      (unauthenticated viewers see everything — see `useRole.ts`).
+ */
+export interface DashboardModelOptions {
+  /**
+   * Hide this model from the dashboard sidebar entirely. Direct
+   * navigation to `/models/<id>` still works — this only suppresses the
+   * sidebar row.
+   *
+   * Defaults to `true` (model is shown).
+   */
+  enabled?: boolean
+
+  /**
+   * Override the display name in the sidebar. Defaults to the model name.
+   */
+  label?: string
+
+  /**
+   * Override the icon. Defaults to the auto-derived one in `iconMap`.
+   * The string is whatever the active sidebar icon set expects
+   * (e.g., SF Symbol name for the native sidebar; Lucide-style name for
+   * the web sidebar).
+   */
+  icon?: string
+
+  /**
+   * Pin this model to a specific sidebar section instead of the
+   * auto-derived category. Useful when a "logs" model lives under
+   * `app/Models/` (userland) but should appear under Management rather
+   * than Data.
+   */
+  section?:
+    | 'home'
+    | 'library'
+    | 'content'
+    | 'commerce'
+    | 'marketing'
+    | 'analytics'
+    | 'management'
+    | 'utilities'
+    | 'data'
+    | 'app'
+
+  /**
+   * Role-gate the sidebar row. The row is rendered server-side with
+   * `data-required-roles="…"`; the client filters it out via
+   * `useRole()` if the viewer doesn't hold any of the listed roles.
+   *
+   * The dev-mode default in `useRole()` means unauthenticated viewers
+   * (e.g., the local dev dashboard) see role-gated rows as if they
+   * were a dev — see `composables/useRole.ts` for the full chain.
+   */
+  roles?: string[]
+
+  /**
+   * Short tooltip / hover description for the sidebar row. Optional —
+   * sidebars that don't support tooltips ignore it.
+   */
+  description?: string
+}

package/src/database.ts

@@ -13,6 +13,20 @@ export interface DatabaseOptions {
       prefix?: string
     }
 
+    // SingleStore is MySQL wire-compatible (port 3306); it shares MySQL's
+    // connection shape and adds an optional `ssl` flag for managed (Helios)
+    // endpoints, which require TLS.
+    singlestore?: {
+      url?: string
+      host?: string
+      port?: number
+      name?: string
+      username?: string
+      password?: string
+      prefix?: string
+      ssl?: boolean
+    }
+
     sqlite: {
       url?: string
       database?: string

package/src/email.ts

@@ -277,6 +277,23 @@ export interface EmailOptions {
   }
 
   mailboxes: string[] | MailboxConfig[]
+
+  /**
+   * Auto-forwarding rules for received mail, provisioned to the mail server's
+   * readable `forwards.json` (re-read on every message — edits take effect
+   * with no restart).
+   *
+   * Key   = the delivered mailbox: the full address for a per-domain isolated
+   *         mailbox (e.g. `'no-reply@acme.com'`), or a bare local-part for a
+   *         legacy role mailbox (e.g. `'postmaster'`).
+   * Value = destination addresses. Targets on a local domain are written
+   *         straight to that mailbox's Maildir; external targets are relayed.
+   *         A copy also stays in the source mailbox.
+   *
+   * @example { 'no-reply@acme.com': ['chris@acme.com'] }
+   */
+  forwards?: Record<string, string[]>
+
   domain?: string
 
   url: string
@@ -286,6 +303,30 @@ export interface EmailOptions {
   notifications?: EmailNotificationsConfig
 
   default: 'log' | 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap' | 'smtp'
+
+  /**
+   * Suppression-list enforcement policy (stacksjs/stacks#1880).
+   *
+   * - `'strict'`                — block all sends to suppressed
+   *   recipients (default)
+   * - `'transactional-allowed'` — block broadcasts; allow messages
+   *   with `tag: 'transactional'`
+   * - `'off'`                   — never block; the suppression
+   *   table is just a tracking record
+   *
+   * The check is opt-in at the table level — apps that haven't
+   * created the `email_suppressions` table see "always allowed"
+   * with a one-shot warn.
+   */
+  suppressionPolicy?: 'strict' | 'transactional-allowed' | 'off'
+
+  /**
+   * URL prefix the framework's default unsubscribe route mounts
+   * under (stacksjs/stacks#1880). Defaults to
+   * `/_stacks/email/unsubscribe`. The full link is built as
+   * `${app.url}${unsubscribeRoute}/${signed-token}`.
+   */
+  unsubscribeRoute?: string
 }
 
 export type EmailConfig = Partial<EmailOptions>
@@ -340,6 +381,17 @@ export interface EmailMessage {
   cc?: string | string[] | EmailAddress[]
   /** Blind carbon copy recipient(s) */
   bcc?: string | string[] | EmailAddress[]
+  /**
+   * Reply-To address(es) for the outgoing message.
+   *
+   * Drivers must propagate this to the provider's equivalent field
+   * (`ReplyToAddresses` on SES, `h:Reply-To` on Mailgun, `reply_to` on
+   * SendGrid, a `Reply-To:` header for SMTP). Previously the field
+   * lived as an `as any` stash on the message (stacksjs/stacks#1871 M-4)
+   * — promoting it to a first-class slot means drivers can be
+   * checked at compile time for coverage.
+   */
+  replyTo?: EmailAddress | EmailAddress[] | string | string[]
   /** Email subject line */
   subject: string
   /** Path to email template (Vue component) */
@@ -364,6 +416,48 @@ export interface EmailMessage {
   onError?: (error: Error) => Promise<{ message: string }> | { message: string }
   /** Optional custom handler */
   handle?: () => Promise<{ message: string }> | { message: string }
+  /**
+   * Caller-supplied idempotency key (stacksjs/stacks#1871 M-8).
+   *
+   * When set, `mail.send()` consults an `email_idempotency` dedup
+   * table before dispatching to the driver:
+   *   - hit: returns the cached EmailResult from the first send
+   *   - miss: dispatches, then records the result under the key
+   *
+   * Why it matters: queued send retries (the framework retries 3×
+   * with backoff) and external retry loops (webhook handlers that
+   * re-fire on transient failures, request POSTs that the user
+   * double-clicks) can otherwise deliver the same email multiple
+   * times. The key turns those retries into safe no-ops.
+   *
+   * Construction guidance: derive the key from the business event
+   * the email represents — e.g. `welcome:${userId}`,
+   * `order-confirmation:${orderId}:${attempt}`, not from message
+   * content (which would collide across unrelated sends).
+   *
+   * The dedup table is opt-in. When the migration hasn't been run
+   * yet, the framework warns once and falls back to "send every
+   * time" so unrelated apps aren't broken by the new behavior.
+   */
+  idempotencyKey?: string
+  /**
+   * Classification used by the suppression-policy check
+   * (stacksjs/stacks#1880). Set to `'transactional'` for messages
+   * that should bypass suppression when
+   * `email.suppressionPolicy: 'transactional-allowed'` is
+   * configured — password resets, billing receipts, magic-link
+   * sign-ins.
+   *
+   * Set to `'broadcast'` (or omit) for marketing / newsletter
+   * sends; those get blocked when the recipient is suppressed.
+   *
+   * Under the default `'strict'` policy this field has no effect
+   * — both transactional and broadcast sends get blocked. Apps
+   * that need to send password-reset emails to bounced addresses
+   * (rare, but legitimate) opt into `'transactional-allowed'` AND
+   * tag the message.
+   */
+  tag?: 'transactional' | 'broadcast'
 }
 
 // Email interfaces

package/src/index.ts

@@ -15,10 +15,17 @@ export * from './cdn'
 export * from './chat'
 export * from './cli'
 export * from './cloud'
+export * from './cms'
+export * from './commerce'
 export * from './components'
 export * from './configure'
+export * from './cors'
 export * from './cron-jobs'
 export * from './dashboard'
+// Module-augments bun-query-builder's BrowserModelDefinition with the
+// stacks `dashboard` slot. Importing this file (transitively via the
+// barrel) is what makes `defineModel({ dashboard: {...} })` typecheck.
+export * from './model-dashboard-augmentation'
 export * from './database'
 export * from './dependencies'
 export * from './deploy'
@@ -37,8 +44,10 @@ export * from './i18n'
 export * from './library'
 export * from './logging'
 export * from './manifest'
+export * from './marketing'
 export * from './model'
 export * from './model-names'
+export * from './monitoring'
 export * from './notifications'
 export * from './pages'
 export * from './payments'

package/src/logging.ts

@@ -25,6 +25,38 @@ export interface LoggingOptions {
    * @default 'storage/logs/deployments.log'
    */
   deploymentsPath: string
+
+  /**
+   * **Minimum Log Level**
+   *
+   * Messages below this level are suppressed. The `LOG_LEVEL` env var
+   * overrides this when set (stacksjs/stacks#1935).
+   *
+   * @default 'info'
+   */
+  level?: 'debug' | 'info' | 'success' | 'warning' | 'error'
+
+  /**
+   * **Output Format**
+   *
+   * `'json'` for structured output (production), `'text'` for the
+   * human-readable dev view. The `LOG_FORMAT` env var overrides this;
+   * default is `'json'` in production, `'text'` otherwise.
+   *
+   * @default 'text'
+   */
+  format?: 'json' | 'text'
+
+  /**
+   * **Write To File**
+   *
+   * Whether logs are persisted to `logsPath`'s directory as daily
+   * files. Set `false` for console-only output (e.g. when the platform
+   * captures stdout).
+   *
+   * @default true
+   */
+  writeToFile?: boolean
 }
 
 export type LoggingConfig = Partial<LoggingOptions>

package/src/marketing.ts

@@ -0,0 +1,14 @@
+/**
+ * **Marketing Options**
+ *
+ * Top-level feature gate for the marketing bundle (`/api/email/subscribe`,
+ * `/api/contact`, Campaign / EmailList / SocialPost). Stays inert at boot
+ * when `enabled` is `false`.
+ */
+export interface MarketingOptions {
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
+}
+
+export type MarketingConfig = Partial<MarketingOptions>

package/src/model-dashboard-augmentation.ts

@@ -0,0 +1,51 @@
+/**
+ * Module augmentation that adds the Stacks-specific `dashboard` slot to
+ * bun-query-builder's `BrowserModelDefinition`.
+ *
+ * Why this lives here (Stacks, not bqb):
+ *
+ *   The `dashboard` config is a Stacks framework concept — it influences
+ *   how the model appears in `buddy dev --dashboard`'s sidebar. It has no
+ *   meaning outside the dashboard surface, so adding it to bqb's core
+ *   types would force every bqb consumer to carry weight they don't need.
+ *
+ * Declaration merging keeps the typing clean at every call site:
+ *
+ *   ```ts
+ *   import { defineModel } from '@stacksjs/orm'
+ *
+ *   defineModel({
+ *     name: 'AuditLog',
+ *     dashboard: { section: 'management', roles: ['admin'] }, // ← typed
+ *     attributes: { … },
+ *   })
+ *   ```
+ *
+ * Without this augmentation, the `dashboard` property would still pass
+ * (because bqb's `defineModel<TDef extends BrowserModelDefinition>` uses
+ * `extends`, which permits excess properties), but with no autocomplete
+ * and no shape validation. The augmentation gives both.
+ *
+ * Loading note: this file only declares types — no runtime effects. It
+ * must be reachable via `@stacksjs/types`' barrel so any package that
+ * already imports from `@stacksjs/types` picks up the augmentation in
+ * the same compilation. Re-exported from `index.ts`.
+ */
+
+import type { DashboardModelOptions } from './dashboard'
+
+declare module 'bun-query-builder' {
+  interface BrowserModelDefinition {
+    /**
+     * Stacks dashboard sidebar configuration for this model.
+     * See {@link DashboardModelOptions} for the full shape.
+     *
+     * Omit to use defaults (model is shown under its auto-categorised
+     * section using `iconMap` + the model name).
+     */
+    readonly dashboard?: DashboardModelOptions
+  }
+}
+
+// Re-export for `import type { DashboardModelOptions } from '@stacksjs/types'`.
+export type { DashboardModelOptions }

package/src/model.ts

@@ -103,10 +103,15 @@ type Action = ActionPath | ActionName | undefined
 
 export type ApiRoutes = 'index' | 'show' | 'store' | 'update' | 'destroy'
 
-export type SocialProviders = 'google' | 'github' | 'twitter' | 'facebook'
+export type SocialProviders = 'google' | 'github' | 'apple' | 'twitter' | 'facebook'
 
 export interface SeedOptions {
   count: number
+  /**
+   * Fixed rows merged over factory output for the first N entries (N = fixtures.length).
+   * Keys use model attribute names (camelCase); stored as snake_case columns.
+   */
+  fixtures?: Array<Record<string, unknown>>
 }
 
 type LogAttribute = string
@@ -185,7 +190,17 @@ export interface ModelOptions extends Base {
     commentables?: boolean // defaults to false
     useAuth?: boolean | UserAuthOptions // defaults to false
     authenticatable?: boolean | UserAuthOptions // useAuth alias
+    /**
+     * @deprecated stacksjs/stacks#1929 — the `useSeeder` trait only
+     * existed to drive the auto-walker, which is removed from
+     * `./buddy seed` (stacksjs/stacks#1919). Seeding is now owned by
+     * class seeders: a `database/seeders/<Model>Seeder.ts` file calling
+     * `factory.generate(Model, { count })`. Run `./buddy seed:scaffold`
+     * to codemod existing traits into seeder files (and strip the
+     * trait). This field is scheduled for removal in the next major.
+     */
     useSeeder?: boolean | SeedOptions // defaults to a count of 10
+    /** @deprecated alias of {@link useSeeder} — see stacksjs/stacks#1929. */
     seedable?: boolean | SeedOptions // useSeeder alias
     useSearch?: boolean | SearchOptions // defaults to false
     useSocials?: SocialOptions // defaults to false
@@ -253,6 +268,23 @@ export interface Attribute {
 export interface CompositeIndex {
   name: string
   columns: string[]
+  /**
+   * Emit `UNIQUE` on the index — turns a multi-column index into a
+   * multi-column unique constraint. Combine with `where:` for a
+   * partial unique index (stacksjs/stacks#1943).
+   *
+   * @default false
+   */
+  unique?: boolean
+  /**
+   * Partial-index `WHERE` clause as a raw SQL expression — e.g.
+   * `'user_id IS NOT NULL'`. Lets the constraint apply to a subset of
+   * rows; the canonical case is "prevent a logged-in user from flagging
+   * the same review twice, but allow anonymous flags (user_id NULL) to
+   * repeat" (stacksjs/stacks#1943). Emitted verbatim, so don't
+   * interpolate untrusted input.
+   */
+  where?: string
 }
 
 export interface AttributesElements {

package/src/monitoring.ts

@@ -0,0 +1,14 @@
+/**
+ * **Monitoring Options**
+ *
+ * Top-level feature gate for the monitoring bundle (Error model +
+ * error-tracking views and actions). Stays inert at boot when `enabled`
+ * is `false`.
+ */
+export interface MonitoringOptions {
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
+}
+
+export type MonitoringConfig = Partial<MonitoringOptions>

package/src/queue.ts

@@ -250,6 +250,14 @@ export interface Dispatchable {
 }
 
 export interface QueueOptions {
+  /**
+   * Top-level feature gate. When `false`, the queue runtime is skipped at
+   * boot (no Job/FailedJob model load, no queue worker startup). Missing or
+   * `true` means the queue feature is on.
+   */
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
   /** Default queue driver */
   default: QueueDriver
   /** Queue connections */