@stacksjs/types 0.70.45 → 0.70.53

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 */

package/src/request.ts

@@ -2,6 +2,10 @@ import type { ModelRow } from '@stacksjs/orm'
 import { User } from '@stacksjs/orm'
 import type { UploadedFile } from '@stacksjs/storage'
 import type { AuthToken, RouteParam } from '@stacksjs/types'
+// `Infer<T extends Validator<U>>` resolves to the validator's output
+// type — `Infer<typeof schema.string()> → string`. Type-only import
+// keeps this package free of a runtime ts-validation dependency.
+import type { Infer } from '@stacksjs/ts-validation'
 
 type UserJsonResponse = ModelRow<typeof User>
 
@@ -9,10 +13,96 @@ interface RequestData {
   [key: string]: any
 }
 
+/**
+ * Loose route-param shape kept around for back-compat with code that
+ * predates {@link RequestInstance}'s `TParams` generic. New code should
+ * rely on the path-extracted `TParams` instead — see {@link ExtractParams}.
+ *
+ * @deprecated Use {@link ExtractParams}-driven typing on the action /
+ *   route signature instead. URL route params are always strings at
+ *   runtime; the `string | number` here misled callers into thinking
+ *   the framework coerced numbers automatically (it doesn't —
+ *   `Number(request.params.id)` is the correct pattern).
+ */
 type RouteParams = { [key: string]: string | number } | null
 
+/**
+ * Legacy hard-coded list of param names treated as `number` by
+ * {@link RequestInstance.getParam}. The name-match heuristic is
+ * brittle (`'judgeId'`, `'user_id'`, etc. all silently fall through
+ * to `string`) and will be retired in a future release.
+ *
+ * @deprecated The name-match returns `number` for these specific keys
+ *   only — pass the value through {@link Number} or
+ *   {@link RequestInstance.getParamAsInt} for explicit, predictable
+ *   coercion. See stacksjs/stacks#1851 Phase 3.
+ */
 type NumericField = 'id' | 'age' | 'count' | 'quantity' | 'amount' | 'price' | 'total' | 'score' | 'rating' | 'duration' | 'size' | 'weight' | 'height' | 'width' | 'length' | 'distance' | 'speed' | 'temperature' | 'volume' | 'capacity' | 'density' | 'pressure' | 'force' | 'energy' | 'power' | 'frequency' | 'voltage' | 'current' | 'resistance' | 'time' | 'date' | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond'
 
+/**
+ * Cookie-access helper exposed via `request.cookies` on
+ * {@link RequestInstance}. The methods mirror bun-router's
+ * `CookieAccessor` — duplicated locally so this package doesn't
+ * have to depend on bun-router for a single type. Keep the surface
+ * in sync if bun-router extends its accessor.
+ */
+export interface RequestCookies {
+  get: (name: string) => string | undefined
+  set: (name: string, value: string, options?: {
+    path?: string
+    domain?: string
+    secure?: boolean
+    httpOnly?: boolean
+    sameSite?: 'strict' | 'lax' | 'none'
+    maxAge?: number
+    expires?: Date
+  }) => void
+  delete: (name: string, options?: { path?: string, domain?: string }) => void
+  getAll: () => Record<string, string>
+}
+
+/**
+ * Template-literal helper that extracts named route params from a
+ * path string (stacksjs/stacks#1851 Phase 2a). Supports both Stacks's
+ * brace-style (`/users/{id}`) and Express-style (`/users/:id`) so a
+ * project using either gets typed `params` out of the box.
+ *
+ * @example
+ *   ExtractParams<'/api/judges/{id}/follow'>  // { id: string }
+ *   ExtractParams<'/api/orders/:orderId/items/:itemId'>  // { orderId: string, itemId: string }
+ *   ExtractParams<'/api/health'>  // Record<string, never>
+ */
+// Step 1: pull the next param name out of either `{name}` or `:name`,
+// recurse on the rest, and union the keys.
+type ExtractParamKeys<S extends string> =
+  // brace form: `…/{name}/…`
+  S extends `${string}{${infer Key}}${infer Rest}`
+    ? Key | ExtractParamKeys<Rest>
+    // colon form: `…/:name/…` (colon must be at a segment boundary
+    // so we don't match `:` inside e.g. a port number; the `/` before
+    // it enforces that)
+    : S extends `${string}/:${infer Key}/${infer Rest}`
+      ? KeyHead<Key> | ExtractParamKeys<`/${Rest}`>
+      // tail colon-form: `…/:name` (no trailing slash)
+      : S extends `${string}/:${infer Key}`
+        ? KeyHead<Key>
+        : never
+
+// `KeyHead<'name>'>` → `'name>'` because TS template literal infers
+// the longest possible match. We need to handle params that are at
+// the end of the path AND followed by a query string. This util
+// truncates a captured key at the first non-name character.
+type KeyHead<S extends string> =
+  S extends `${infer H}/${string}` ? H :
+    S extends `${infer H}?${string}` ? H :
+      S extends `${infer H}.${string}` ? H :
+        S
+
+export type ExtractParams<S extends string> =
+  [ExtractParamKeys<S>] extends [never]
+    ? Record<string, never>
+    : { [K in ExtractParamKeys<S>]: string }
+
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE'
 
 /**
@@ -103,9 +193,35 @@ export interface SafeData<T extends Record<string, any> = Record<string, any>> {
  * })
  * ```
  */
-export type ActionRequest<TFields extends Record<string, any> = Record<string, any>> = RequestInstance<TFields>
+export type ActionRequest<
+  TFields extends Record<string, any> = Record<string, any>,
+  TParams extends Record<string, string> = Record<string, string>,
+> = RequestInstance<TFields, TParams>
 
-export interface RequestInstance<TFields extends Record<string, any> = Record<string, any>> {
+/**
+ * Read the body shape declared by an action's `validations:` field as
+ * a TypeScript object type (stacksjs/stacks#1851 Phase 2b). Threaded
+ * into {@link RequestInstance}'s `TFields` so `request.all()` returns
+ * the body shape with the field types {@link Infer}'d from each
+ * `schema.X()` rule.
+ *
+ * @example
+ *   const validations = {
+ *     email:    { rule: schema.string().email() },
+ *     password: { rule: schema.string().min(8) },
+ *     remember: { rule: schema.boolean() },
+ *   } as const
+ *   type Body = InferValidations<typeof validations>
+ *   // → { email: string, password: string, remember: boolean }
+ */
+export type InferValidations<V extends Record<string, { rule: any }>> = {
+  [K in keyof V]: Infer<V[K]['rule']>
+}
+
+export interface RequestInstance<
+  TFields extends Record<string, any> = Record<string, any>,
+  TParams extends Record<string, string> = Record<string, string>,
+> {
   // ==========================================================================
   // Native Request properties
   // ==========================================================================
@@ -116,10 +232,28 @@ export interface RequestInstance<TFields extends Record<string, any> = Record<st
 
   // Raw data access (always untyped — use get()/input() for typed access)
   query: RequestData
-  params: RouteParams
+  /**
+   * Route parameters from the URL. When the action is bound to a path
+   * literal (via {@link ActionOptions.path} or a typed
+   * `route.get<TPath>(...)` overload), `TParams` narrows to the
+   * extracted keys so `request.params.id` is `string` with no `as any`.
+   *
+   * For un-narrowed callers (bare `RequestInstance`), this falls
+   * back to `Record<string, string>` — the runtime shape is always
+   * string-keyed even for "numeric" params, since URL segments are
+   * never coerced.
+   */
+  params: TParams
   jsonBody?: any
   formBody?: any
   files: Record<string, File | File[]>
+  /**
+   * Cookies parsed from the request. The accessor exposes
+   * `get`/`set`/`delete`/`getAll` helpers that mirror bun-router's
+   * cookie handling. Optional because not every request middleware
+   * stack runs the cookie parser.
+   */
+  cookies?: RequestCookies
 
   // ==========================================================================
   // Model-aware Input Methods
@@ -325,12 +459,39 @@ export interface RequestInstance<TFields extends Record<string, any> = Record<st
   bearerToken: () => string | null | AuthToken
 
   // ==========================================================================
-  // Route & Param Methods — not narrowed to model fields
+  // Route & Param Methods
+  //
+  // `params` (the field above) is the typed primary surface — narrow
+  // it via the action's `path:` literal for full inference. These
+  // method-form helpers stay around for back-compat and for cases
+  // where the param key isn't statically known.
   // ==========================================================================
 
+  /**
+   * Look up a single route param, optionally with a default. Narrows
+   * to {@link TParams} when the key is part of the path-extracted
+   * keyset; falls back to `string | undefined` otherwise (covers
+   * dynamic key access without `as any`).
+   *
+   * @example
+   *   const id = request.param('id')              // typed string (from path)
+   *   const note = request.param('note', '')      // string with default
+   */
+  param: <K extends keyof TParams | string, D = string>(
+    key: K,
+    defaultValue?: D,
+  ) => K extends keyof TParams ? TParams[K] : (string | D)
+  /**
+   * @deprecated Use {@link param} for typed param lookups, or
+   *   `Number(request.params.id)` for explicit numeric coercion.
+   *   The name-match heuristic returning `number` for {@link NumericField}
+   *   keys (`id`, `count`, `amount`, …) is brittle: it silently falls
+   *   through to `string` for `judgeId`, `user_id`, etc.
+   *   See stacksjs/stacks#1851 Phase 3.
+   */
   getParam: <K extends string>(key: K) => K extends NumericField ? number : string
   route: (key: string) => number | string | null
-  getParams: () => RouteParams
+  getParams: () => TParams
   getParamAsInt: (key: string) => number | null
 
   // ==========================================================================

package/src/search-engine.ts

@@ -40,7 +40,7 @@ export interface SearchEngineOptions {
    * @default string 'meilisearch'
    * @see https://stacksjs.com/docs/search-engine
    */
-  driver: 'meilisearch' | 'algolia' | 'opensearch'
+  driver: 'meilisearch' | 'algolia' | 'opensearch' | 'typesense'
 
   opensearch?: {
     host: string
@@ -63,6 +63,13 @@ export interface SearchEngineOptions {
     searchOnlyApiKey?: string
   }
 
+  typesense?: {
+    host?: string
+    port?: number
+    protocol?: string
+    apiKey?: string
+  }
+
   filters?: {
     [key: string]: string
   }
@@ -204,6 +211,30 @@ export interface SearchOptions {
   sortable: string[]
   filterable: string[]
   options?: SearchEngineOptions
+  /**
+   * Cross-table denormalisation for searchable fields that live on a
+   * related model (stacksjs/stacks#1918). Maps an indexed-document
+   * field name to a dot-path resolved against the model instance's
+   * `_relations`. Without this, `toSearchableObject` only reads from
+   * `_attributes` and silently emits `undefined` for any field that
+   * exists on a `belongsTo` / `hasOne` / `hasMany` relation.
+   *
+   * Example: a `Judge` belongsTo a `CourtHouse`. To make the court
+   * house's `name` searchable on the judge index:
+   *
+   *   useSearch: {
+   *     searchable:  ['name', 'court_name'],
+   *     displayable: ['id', 'name', 'court_name'],
+   *     denormalize: { court_name: 'court_house.name' },
+   *   }
+   *
+   * The caller is responsible for eager-loading the named relations
+   * (e.g. via `Judge.query().with('court_house').get()`) — the live
+   * observer hook and the CLI bulk-index path do this automatically
+   * for every distinct head segment in the `denormalize` map.
+   * `toSearchableObject` stays synchronous; no per-row database lookup.
+   */
+  denormalize?: Record<string, string>
 }
 
 export type {

package/src/services.ts

@@ -25,6 +25,24 @@ export interface ServicesOptions {
     scopes?: string[]
   }
 
+  /**
+   * Sign in with Apple. Apple has no static client secret — the driver
+   * signs a short-lived ES256 JWT from teamId + keyId + privateKey
+   * (the .p8 file's contents) instead.
+   */
+  apple?: {
+    /** The Services ID identifier, e.g. `org.example.web` */
+    clientId: string
+    /** Apple Developer Team ID (10 chars) */
+    teamId: string
+    /** Key ID of the "Sign in with Apple" key */
+    keyId: string
+    /** Contents of the downloaded .p8 private key */
+    privateKey: string
+    redirectUrl: string
+    scopes?: string[]
+  }
+
   facebook?: {
     clientId: string
     clientSecret: string
@@ -168,6 +186,14 @@ export interface ServicesOptions {
   stripe?: {
     secretKey?: string
     publicKey?: string
+    /**
+     * Signing secret for verifying inbound Stripe webhook requests
+     * (`whsec_...`, from the Stripe dashboard's webhook endpoint
+     * config). Required by any app receiving Stripe webhooks —
+     * without it, `stripe.webhooks.constructEvent` has nothing to
+     * verify the `stripe-signature` header against.
+     */
+    webhookSecret?: string
     /**
      * Pinned Stripe API version. Defaults to whatever the bundled SDK
      * was compiled against; override here when rolling forward without

package/src/stacks.ts

@@ -6,6 +6,9 @@ import type {
   BinaryConfig,
   CacheConfig,
   CloudConfig,
+  CmsConfig,
+  CommerceConfig,
+  CorsConfig,
   DashboardConfig,
   DatabaseConfig,
   DnsConfig,
@@ -17,6 +20,8 @@ import type {
   HashingConfig,
   LibraryConfig,
   LoggingConfig,
+  MarketingConfig,
+  MonitoringConfig,
   NotificationConfig,
   PaymentConfig,
   Ports,
@@ -67,6 +72,14 @@ export interface StacksOptions {
    */
   auth: AuthConfig
 
+  /**
+   * **CORS Options**
+   *
+   * Cross-origin resource sharing policy applied to API responses.
+   * Configured via `config/cors.ts`. See {@link CorsConfig}.
+   */
+  cors?: CorsConfig
+
   /**
    * **Realtime Options**
    *
@@ -103,12 +116,26 @@ export interface StacksOptions {
    */
   cloud: CloudConfig
 
+  /**
+   * **CMS Options**
+   *
+   * Top-level feature gate for the CMS bundle (Post / Page / Author /
+   * Comment / Tag / Category models + content-edit dashboards).
+   */
+  cms: CmsConfig
+
+  /**
+   * **Commerce Options**
+   *
+   * Top-level feature gate for the commerce bundle plus storefront defaults.
+   */
+  commerce: CommerceConfig
+
   /**
    * **Dashboard Options**
    *
-   * Controls which sections render in the `buddy dev --dashboard` sidebar.
-   * Set per-section `enabled` flags to `false` to hide a section that this
-   * project doesn't use (e.g. `commerce.enabled: false`).
+   * Top-level feature gate plus per-section visibility toggles for the
+   * `buddy dev --dashboard` sidebar.
    */
   dashboard: DashboardConfig
 
@@ -193,6 +220,22 @@ export interface StacksOptions {
    */
   logging: LoggingConfig
 
+  /**
+   * **Marketing Options**
+   *
+   * Top-level feature gate for the marketing bundle (`/api/email/subscribe`,
+   * `/api/contact`, Campaign / EmailList / SocialPost).
+   */
+  marketing: MarketingConfig
+
+  /**
+   * **Monitoring Options**
+   *
+   * Top-level feature gate for the monitoring bundle (Error model +
+   * error-tracking views and actions).
+   */
+  monitoring: MonitoringConfig
+
   /**
    * **Notification Options**
    *