@stacksjs/types 0.70.44 → 0.70.53

package/dist/request.d.ts

@@ -1,10 +1,32 @@
 import { User } from '@stacksjs/orm';
 import type { AuthToken } from '@stacksjs/types';
+import type { Infer } from '@stacksjs/ts-validation';
 import type { ModelRow } from '@stacksjs/orm';
 import type { UploadedFile } from '@stacksjs/storage';
 declare interface RequestData {
   [key: string]: any
 }
+/**
+ * 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 declare 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>
+}
 /**
  * Collection interface for array data (Laravel-style)
  */
@@ -45,15 +67,16 @@ export declare interface SafeData<T extends Record<string, any> = Record<string,
   has: (key: keyof T) => boolean
   get: <K extends keyof T>(key: K) => T[K]
 }
-export declare interface RequestInstance<TFields extends Record<string, any> = Record<string, any>> {
+export declare interface RequestInstance<TFields extends Record<string, any> = Record<string, any>, TParams extends Record<string, string> = Record<string, string>,> {
   url: string
   method: string
   headers: Headers
   query: RequestData
-  params: RouteParams
+  params: TParams
   jsonBody?: any
   formBody?: any
   files: Record<string, File | File[]>
+  cookies?: RequestCookies
   get: <K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]) => TFields[K]
   input: <K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]) => TFields[K]
   all: () => TFields
@@ -85,9 +108,13 @@ export declare interface RequestInstance<TFields extends Record<string, any> = R
   allFiles: () => Record<string, UploadedFile | UploadedFile[]>
   header: (key: string) => string | null
   bearerToken: () => string | null | AuthToken
+  param: <K extends keyof TParams | string, D = string>(
+    key: K,
+    defaultValue?: D,
+  ) => K extends keyof TParams ? TParams[K] : (string | D)
   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
   old: <T = unknown>(key: keyof TFields & string, defaultValue?: T) => T
   flashInput: (keys?: (keyof TFields & string)[]) => void
@@ -102,8 +129,65 @@ export declare interface RequestInstance<TFields extends Record<string, any> = R
   user: () => Promise<UserJsonResponse | undefined>
 }
 declare type UserJsonResponse = ModelRow<typeof User>;
+/**
+ * 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).
+ */
 declare 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.
+ */
 declare 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';
+/**
+ * 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.
+declare type ExtractParamKeys<S extends string> = 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.
+declare 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';
 /**
  * RequestInstance - Generic, model-aware request interface with Laravel-style methods.
@@ -151,4 +235,23 @@ export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' |
  * })
  * ```
  */
-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>;
+/**
+ * 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']>
+}

package/dist/search-engine.d.ts

@@ -24,7 +24,7 @@ export type {
 // type Sorts = any
 // type Sort = any
 export declare interface SearchEngineOptions {
-  driver: 'meilisearch' | 'algolia' | 'opensearch'
+  driver: 'meilisearch' | 'algolia' | 'opensearch' | 'typesense'
   opensearch?: {
     host: string
     protocol: number
@@ -43,6 +43,12 @@ export declare interface SearchEngineOptions {
     apiKey: string
     searchOnlyApiKey?: string
   }
+  typesense?: {
+    host?: string
+    port?: number
+    protocol?: string
+    apiKey?: string
+  }
   filters?: {
     [key: string]: string
   }
@@ -118,5 +124,6 @@ export declare interface SearchOptions {
   sortable: string[]
   filterable: string[]
   options?: SearchEngineOptions
+  denormalize?: Record<string, string>
 }
 export type SearchEngineConfig = Partial<SearchEngineOptions>;

package/dist/services.d.ts

@@ -21,6 +21,14 @@ export declare interface ServicesOptions {
     redirectUrl: string
     scopes?: string[]
   }
+  apple?: {
+    clientId: string
+    teamId: string
+    keyId: string
+    privateKey: string
+    redirectUrl: string
+    scopes?: string[]
+  }
   facebook?: {
     clientId: string
     clientSecret: string
@@ -134,6 +142,7 @@ export declare interface ServicesOptions {
   stripe?: {
     secretKey?: string
     publicKey?: string
+    webhookSecret?: string
     apiVersion?: string
   }
 }

package/dist/stacks.d.ts

@@ -1,4 +1,4 @@
-import type { AiConfig, AnalyticsConfig, AppConfig, AuthConfig, BinaryConfig, CacheConfig, CloudConfig, DashboardConfig, DatabaseConfig, DnsConfig, DocsConfig, EmailConfig, ErrorConfig, FilesystemsConfig, GitConfig, HashingConfig, LibraryConfig, LoggingConfig, NotificationConfig, PaymentConfig, Ports, QueueConfig, RealtimeConfig, SaasConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, Team, UiConfig } from '.';
+import type { AiConfig, AnalyticsConfig, AppConfig, AuthConfig, BinaryConfig, CacheConfig, CloudConfig, CmsConfig, CommerceConfig, CorsConfig, DashboardConfig, DatabaseConfig, DnsConfig, DocsConfig, EmailConfig, ErrorConfig, FilesystemsConfig, GitConfig, HashingConfig, LibraryConfig, LoggingConfig, MarketingConfig, MonitoringConfig, NotificationConfig, PaymentConfig, Ports, QueueConfig, RealtimeConfig, SaasConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, Team, UiConfig } from '.';
 /**
  * **Stacks Options**
  *
@@ -11,10 +11,13 @@ export declare interface StacksOptions {
   analytics: AnalyticsConfig
   app: AppConfig
   auth: AuthConfig
+  cors?: CorsConfig
   realtime: RealtimeConfig
   cache: CacheConfig
   cli: BinaryConfig
   cloud: CloudConfig
+  cms: CmsConfig
+  commerce: CommerceConfig
   dashboard: DashboardConfig
   database: DatabaseConfig
   dns: DnsConfig
@@ -25,6 +28,8 @@ export declare interface StacksOptions {
   hashing: HashingConfig
   library: LibraryConfig
   logging: LoggingConfig
+  marketing: MarketingConfig
+  monitoring: MonitoringConfig
   notification: NotificationConfig
   payment: PaymentConfig
   ports: Ports

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/types",
   "type": "module",
-  "version": "0.70.44",
+  "version": "0.70.53",
   "description": "The Stacks framework types.",
   "author": "Chris Breuer",
   "contributors": [
@@ -45,12 +45,12 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/bunpress": "^0.1.4",
-    "@stacksjs/ts-validation": "^0.4.10",
-    "bun-query-builder": "^0.1.21"
+    "@stacksjs/bunpress": "^0.1.11",
+    "@stacksjs/ts-validation": "^0.5.0",
+    "bun-query-builder": "^0.1.38"
   },
   "devDependencies": {
-    "@stacksjs/validation": "^0.70.44",
+    "@stacksjs/validation": "0.70.53",
     "@types/bun": "^1.3.11",
     "typescript": "^5.9.3"
   },

package/src/auth.ts

@@ -1,4 +1,12 @@
 export interface AuthOptions {
+  /**
+   * Top-level feature gate. When `false`, the auth feature is inert at boot
+   * (no token/password-reset/email-verification flows wired up). Missing or
+   * `true` means auth is on.
+   */
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
   /**
    * The default authentication guard to use
    */
@@ -90,6 +98,37 @@ export interface AuthOptions {
      * @default 60
      */
     throttle: number
+
+    /**
+     * Reset-link URL template. Supports `{token}` and `{email}`
+     * placeholders. Absolute templates (`https://…`) are used as-is;
+     * path templates are prefixed with the app URL. Lets apps whose
+     * reset page lives on a custom route reuse `passwordResets().sendEmail()`
+     * instead of hand-rolling the send.
+     * @default '/password/reset/{token}?email={email}'
+     */
+    url?: string
+  }
+
+  /**
+   * Email verification configuration
+   */
+  emailVerification?: {
+    /**
+     * Token expiration time in minutes
+     * @default 60
+     */
+    expire?: number
+
+    /**
+     * Verification-link URL template. Supports `{id}` and `{token}`
+     * placeholders. Absolute templates (`https://…`) are used as-is;
+     * path templates are prefixed with the app URL. Lets apps whose
+     * verify page lives on a custom route reuse `sendVerificationEmail()`
+     * instead of hand-rolling the send.
+     * @default '/verify-email/{id}/{token}'
+     */
+    url?: string
   }
 }
 

package/src/cache.ts

@@ -6,11 +6,15 @@ export interface CacheOptions {
    * **Cache Driver**
    *
    * The cache driver that will be used by your application to store
-   * cached data. Supports 'memory' and 'redis' drivers.
+   * cached data. Supports 'memory', 'redis', and 'singlestore' drivers.
+   *
+   * The 'singlestore' driver persists cache entries in a SingleStore
+   * rowstore table (with epoch-based TTL) — useful when you want a single
+   * SingleStore cluster to back both your primary data and your cache.
    *
    * @default "memory"
    */
-  driver: 'memory' | 'redis'
+  driver: 'memory' | 'redis' | 'singlestore'
 
   /**
    * **Cache Prefix**
@@ -117,6 +121,49 @@ export interface CacheOptions {
        */
       deleteOnExpire?: boolean
     }
+
+    singlestore?: {
+      /**
+       * SingleStore host (MySQL wire protocol)
+       * @default "127.0.0.1"
+       */
+      host?: string
+
+      /**
+       * SingleStore port
+       * @default 3306
+       */
+      port?: number
+
+      /**
+       * SingleStore username
+       * @default "root"
+       */
+      username?: string
+
+      /**
+       * SingleStore password
+       */
+      password?: string
+
+      /**
+       * Database that holds the cache table
+       * @default "stacks"
+       */
+      database?: string
+
+      /**
+       * Table used to store cache entries
+       * @default "stacks_cache"
+       */
+      table?: string
+
+      /**
+       * Enable TLS (required by managed SingleStore / Helios)
+       * @default false
+       */
+      ssl?: boolean
+    }
   }
 }
 

package/src/cli.ts

@@ -238,6 +238,7 @@ export type CreateBooleanOption =
   | 'functions'
   | 'api'
   | 'database'
+  | 'minimal'
 export type CreateOptions = {
   [key in CreateBooleanOption]: boolean
 } & {
@@ -250,6 +251,7 @@ export type DevOption =
   | 'frontend'
   | 'api'
   | 'desktop'
+  | 'native'
   | 'all'
   | 'email'
   | 'system-tray'

package/src/cms.ts

@@ -0,0 +1,14 @@
+/**
+ * **CMS Options**
+ *
+ * Top-level feature gate plus any future CMS-wide settings. The CMS bundle
+ * (Post / Page / Author / Comment / Tag / Category models + edit dashboards)
+ * stays inert at boot when `enabled` is `false`.
+ */
+export interface CmsOptions {
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
+}
+
+export type CmsConfig = Partial<CmsOptions>

package/src/commerce.ts

@@ -0,0 +1,18 @@
+/**
+ * **Commerce Options**
+ *
+ * Top-level feature gate plus storefront defaults. The commerce bundle
+ * (Order / Cart / Product / Customer / Coupon / GiftCard / Shipping models +
+ * storefront API) stays inert at boot when `enabled` is `false`.
+ */
+export interface CommerceOptions {
+  enabled?: boolean
+  /** Optional deploy-target gate, e.g. `['production']`. */
+  env?: string[]
+  /** Default storefront currency (ISO 4217), e.g. `'USD'`. */
+  currency?: string
+  /** Default tax rate applied when no product/region rule overrides. */
+  defaultTaxRate?: number
+}
+
+export type CommerceConfig = Partial<CommerceOptions>

package/src/cors.ts

@@ -0,0 +1,86 @@
+/**
+ * CORS configuration types (stacksjs/stacks#1859 H-2).
+ *
+ * Lives in `@stacksjs/types` so userland `config/cors.ts` files can
+ * `import type { CorsConfig } from '@stacksjs/types'` and get full
+ * IntelliSense, and so the Cors middleware can read
+ * `config.cors` with proper typing instead of an `as any` cast.
+ */
+
+/**
+ * Raw CORS configuration — every field optional. Defaults fill in
+ * any field that's missing when the middleware resolves config.
+ *
+ * @example
+ * ```ts
+ * // config/cors.ts
+ * import type { CorsConfig } from '@stacksjs/types'
+ *
+ * export default {
+ *   origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   credentials: true,
+ *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *   allowedHeaders: ['Content-Type', 'Authorization', 'X-CSRF-Token'],
+ *   maxAge: 600,
+ * } satisfies CorsConfig
+ * ```
+ */
+export interface CorsConfig {
+  /**
+   * Allowed origins.
+   *
+   * - `'*'` permits any origin (incompatible with `credentials: true`).
+   * - A string array enumerates the explicit allow-list; the request's
+   *   `Origin` header is reflected verbatim when it matches.
+   * - A predicate function lets you implement dynamic allow-lists
+   *   (e.g. wildcards, regex, environment-dependent).
+   */
+  origin?: '*' | string[] | ((origin: string) => boolean)
+
+  /**
+   * HTTP methods the server accepts cross-origin. Echoed back in
+   * preflight `Access-Control-Allow-Methods` responses.
+   */
+  methods?: string[]
+
+  /**
+   * Request headers the browser is allowed to send cross-origin.
+   * Echoed back in preflight `Access-Control-Allow-Headers` responses.
+   */
+  allowedHeaders?: string[]
+
+  /**
+   * Response headers the browser is allowed to expose to JS via
+   * `fetch(...).then(r => r.headers.get(...))`. Anything not listed
+   * here is hidden from the SPA even though it's on the wire.
+   */
+  exposedHeaders?: string[]
+
+  /**
+   * Whether cookies / Authorization headers may be included
+   * cross-origin. **Setting this to `true` is incompatible with
+   * `origin: '*'`** — the spec requires an explicit origin.
+   */
+  credentials?: boolean
+
+  /**
+   * How long the browser may cache the preflight response, in
+   * seconds. Default 86_400 (24h). Lower values cost more preflights
+   * but pick up policy changes faster.
+   */
+  maxAge?: number
+}
+
+/**
+ * Resolved CORS configuration with all defaults applied. This is the
+ * shape the middleware passes through `applyCorsHeaders` /
+ * `buildPreflightResponse`.
+ */
+export interface ResolvedCorsConfig {
+  origin: '*' | string[] | ((origin: string) => boolean)
+  methods: string[]
+  allowedHeaders: string[]
+  exposedHeaders: string[]
+  credentials: boolean
+  maxAge: number
+}