@lenne.tech/nest-server 11.29.1 → 11.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/FRAMEWORK-API.md +157 -157
  2. package/dist/tsconfig.build.tsbuildinfo +1 -1
  3. package/migration-guides/11.29.x-to-11.30.x.md +98 -0
  4. package/package.json +13 -14
  5. package/src/core/modules/ai/README.md +1 -3
  6. package/src/core/modules/better-auth/README.md +8 -7
package/FRAMEWORK-API.md CHANGED
@@ -1,228 +1,228 @@
1
1
  # @lenne.tech/nest-server — Framework API Reference
2
2
 
3
- > Auto-generated from source code on 2026-07-17 (v11.29.1)
3
+ > Auto-generated from source code on 2026-07-18 (v11.30.0)
4
4
  > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
5
5
 
6
6
  ## CoreModule.forRoot()
7
7
 
8
- - `CoreModule.forRoot(options: Partial<IServerOptions>, overrides?: ICoreModuleOverrides)`: `DynamicModule`
9
- - ~~`CoreModule.forRoot(AuthService: any, AuthModule: any, options: Partial<IServerOptions>, overrides?: ICoreModuleOverrides)`: `DynamicModule`~~ *(deprecated)*
8
+ - `CoreModule.forRoot(options: Partial<IServerOptions>, overrides?: ICoreModuleOverrides | undefined)`: `DynamicModule`
9
+ - ~~`CoreModule.forRoot(AuthService: any, AuthModule: any, options: Partial<IServerOptions>, overrides?: ICoreModuleOverrides | undefined)`: `DynamicModule`~~ *(deprecated)*
10
10
 
11
11
  ## Configuration Interfaces
12
12
 
13
13
  ### IServerOptions
14
14
 
15
- - `ai?`: `boolean | IAi` — Configuration for the AI assistant module.
16
- - `appUrl?`: `string` — Base URL of the frontend/app application.
17
- - `auth?`: `IAuth` — Authentication system configuration
18
- - `automaticObjectIdFiltering?`: `boolean` — Automatically detect ObjectIds in string values in FilterQueries
19
- - `baseUrl?`: `string` — Base URL of the API server.
20
- - `betterAuth?`: `boolean | IBetterAuth` (default: `undefined (enabled with defaults)`) — Configuration for better-auth authentication framework.
21
- - `brevo?`: `{ apiKey: string; exclude?: RegExp; sender: { email: string; name: string; }; }` — Configuration for Brevo
22
- - `compression?`: `boolean | compression.CompressionOptions` — Whether to use the compression middleware package to enable gzip compression.
23
- - `cookies?`: `boolean | ICookiesConfig` (default: `true`) — Cookie configuration for authentication handling.
24
- - `cors?`: `boolean | ICorsConfig` (default: `undefined (enabled with auto-derived origins)`) — CORS (Cross-Origin Resource Sharing) configuration.
15
+ - `ai?`: `boolean | IAi | undefined` — Configuration for the AI assistant module.
16
+ - `appUrl?`: `string | undefined` — Base URL of the frontend/app application.
17
+ - `auth?`: `IAuth | undefined` — Authentication system configuration
18
+ - `automaticObjectIdFiltering?`: `boolean | undefined` — Automatically detect ObjectIds in string values in FilterQueries
19
+ - `baseUrl?`: `string | undefined` — Base URL of the API server.
20
+ - `betterAuth?`: `boolean | IBetterAuth | undefined` (default: `undefined (enabled with defaults)`) — Configuration for better-auth authentication framework.
21
+ - `brevo?`: `{ apiKey: string; exclude?: RegExp; sender: { email: string; name: string; };...` — Configuration for Brevo
22
+ - `compression?`: `boolean | compression.CompressionOptions | undefined` — Whether to use the compression middleware package to enable gzip compression.
23
+ - `cookies?`: `boolean | ICookiesConfig | undefined` (default: `true`) — Cookie configuration for authentication handling.
24
+ - `cors?`: `boolean | ICorsConfig | undefined` (default: `undefined (enabled with auto-derived origins)`) — CORS (Cross-Origin Resource Sharing) configuration.
25
25
  - `cronJobs?`: `Record<string, string | false | 0 | CronJobConfigWithTimeZone<null, null> | C...` — Cron jobs configuration object with the name of the cron job function as key
26
- - `debugProcessInput?`: `boolean` (default: `false`) — When true, logs a debug message when prepareInput() changes the input type during process().
26
+ - `debugProcessInput?`: `boolean | undefined` (default: `false`) — When true, logs a debug message when prepareInput() changes the input type during process().
27
27
  - `email?`: `{ defaultSender?: { email?: string; name?: string; }; mailjet?: MailjetOption...` — SMTP and template configuration for sending emails
28
- - `env?`: `string` — Environment
29
- - `version?`: `string` — Semantic version of the running build (e.g. from package.json / meta.json).
30
- - `errorCode?`: `IErrorCode` — Configuration for the error code module
31
- - `execAfterInit?`: `string` — Exec a command after server is initialized
32
- - `filter?`: `{ maxLimit?: number; }` — Filter configuration and defaults
28
+ - `env?`: `string | undefined` — Environment
29
+ - `version?`: `string | undefined` — Semantic version of the running build (e.g. from package.json / meta.json).
30
+ - `errorCode?`: `IErrorCode | undefined` — Configuration for the error code module
31
+ - `execAfterInit?`: `string | undefined` — Exec a command after server is initialized
32
+ - `filter?`: `{ maxLimit?: number; } | undefined` — Filter configuration and defaults
33
33
  - `graphQl?`: `false | { driver?: ApolloDriverConfig; enableSubscriptionAuth?: boolean; maxC...` — Configuration of the GraphQL module
34
34
  - `healthCheck?`: `{ configs?: { build?: { enabled?: boolean; }; database?: { enabled?: boolean;...` — Whether to activate health check endpoints
35
- - `hostname?`: `string` — Hostname of the server
36
- - `ignoreSelectionsForPopulate?`: `boolean` — Ignore selections in fieldSelection
37
- - `jwt?`: `IJwt & JwtModuleOptions & { refresh?: IJwt & { renewal?: boolean; }; sameToke...` — Configuration of JavaScript Web Token (JWT) module
38
- - `loadLocalConfig?`: `string | boolean` — Load local configuration
39
- - `logExceptions?`: `boolean` — Log exceptions (for better debugging)
35
+ - `hostname?`: `string | undefined` — Hostname of the server
36
+ - `ignoreSelectionsForPopulate?`: `boolean | undefined` — Ignore selections in fieldSelection
37
+ - `jwt?`: `(IJwt & JwtModuleOptions & { refresh?: IJwt & { renewal?: boolean; }; sameTok...` — Configuration of JavaScript Web Token (JWT) module
38
+ - `loadLocalConfig?`: `string | boolean | undefined` — Load local configuration
39
+ - `logExceptions?`: `boolean | undefined` — Log exceptions (for better debugging)
40
40
  - `mongoose?`: `{ collation?: CollationOptions; modelDocumentation?: boolean; options?: Mongo...` — Configuration for Mongoose
41
- - `multiTenancy?`: `IMultiTenancy` (default: `undefined (disabled)`) — Multi-tenancy configuration for tenant-based data isolation.
42
- - `permissions?`: `boolean | IPermissions` (default: `undefined (disabled)`) — Permissions report module (development tool).
43
- - `port?`: `number` — Port number of the server
41
+ - `multiTenancy?`: `IMultiTenancy | undefined` (default: `undefined (disabled)`) — Multi-tenancy configuration for tenant-based data isolation.
42
+ - `permissions?`: `boolean | IPermissions | undefined` (default: `undefined (disabled)`) — Permissions report module (development tool).
43
+ - `port?`: `number | undefined` — Port number of the server
44
44
  - `security?`: `{ checkResponseInterceptor?: boolean | { checkObjectItself?: boolean; debug?:...` — Configuration for security pipes and interceptors
45
- - `sha256?`: `boolean` — Whether to enable verification and automatic encryption for received passwords that are not in sha256 format
46
- - `staticAssets?`: `{ options?: ServeStaticOptions; path?: string; }` — Configuration for useStaticAssets
47
- - `systemSetup?`: `ISystemSetup` — System setup configuration for initial admin creation.
48
- - `templates?`: `{ engine?: string; path?: string; }` — Templates
49
- - `tus?`: `boolean | ITusConfig` — TUS resumable upload configuration.
45
+ - `sha256?`: `boolean | undefined` — Whether to enable verification and automatic encryption for received passwords that are not in sha256 format
46
+ - `staticAssets?`: `{ options?: ServeStaticOptions; path?: string; } | undefined` — Configuration for useStaticAssets
47
+ - `systemSetup?`: `ISystemSetup | undefined` — System setup configuration for initial admin creation.
48
+ - `templates?`: `{ engine?: string; path?: string; } | undefined` — Templates
49
+ - `tus?`: `boolean | ITusConfig | undefined` — TUS resumable upload configuration.
50
50
 
51
51
  ### IBetterAuth (type alias: IBetterAuthWithoutPasskey | IBetterAuthWithPasskey)
52
52
 
53
53
  When `passkey` is enabled, `trustedOrigins` is required (compile-time enforcement).
54
54
 
55
55
  - `passkey?`: `IBetterAuthPasskeyDisabled` — Passkey/WebAuthn configuration (DISABLED or not configured).
56
- - `trustedOrigins?`: `string[]` — Trusted origins for CORS configuration.
56
+ - `trustedOrigins?`: `string[] | undefined` — Trusted origins for CORS configuration.
57
57
 
58
58
  ### IAuth
59
59
 
60
- - `legacyEndpoints?`: `IAuthLegacyEndpoints` — Configuration for legacy auth endpoints
61
- - `preventUserEnumeration?`: `boolean` (default: `false (backward compatible - specific error messages)`) — Prevent user enumeration via unified error messages
62
- - `rateLimit?`: `IAuthRateLimit` (default: `{ enabled: false }`) — Rate limiting configuration for Legacy Auth endpoints
60
+ - `legacyEndpoints?`: `IAuthLegacyEndpoints | undefined` — Configuration for legacy auth endpoints
61
+ - `preventUserEnumeration?`: `boolean | undefined` (default: `false (backward compatible - specific error messages)`) — Prevent user enumeration via unified error messages
62
+ - `rateLimit?`: `IAuthRateLimit | undefined` (default: `{ enabled: false }`) — Rate limiting configuration for Legacy Auth endpoints
63
63
 
64
64
  ### IMultiTenancy
65
65
 
66
- - `enabled?`: `boolean` (default: `true (when config object is present)`) — Explicitly disable multi-tenancy even when config is present.
67
- - `excludeSchemas?`: `string[]` — Model names (NOT collection names) to exclude from tenant filtering.
68
- - `headerName?`: `string` (default: `'x-tenant-id'`) — Header name for tenant selection.
69
- - `membershipModel?`: `string` (default: `'TenantMember'`) — Mongoose model name for the membership collection.
70
- - `adminBypass?`: `boolean` (default: `true`) — Whether system admins (RoleEnum.ADMIN) bypass the membership check.
71
- - `roleHierarchy?`: `Record<string, number>` (default: `{ member: 1, manager: 2, owner: 3 }`) — Custom role hierarchy for tenant membership roles.
72
- - `cacheTtlMs?`: `number` (default: `30000 (30 seconds)`) — TTL in milliseconds for the tenant guard's in-memory membership cache.
66
+ - `enabled?`: `boolean | undefined` (default: `true (when config object is present)`) — Explicitly disable multi-tenancy even when config is present.
67
+ - `excludeSchemas?`: `string[] | undefined` — Model names (NOT collection names) to exclude from tenant filtering.
68
+ - `headerName?`: `string | undefined` (default: `'x-tenant-id'`) — Header name for tenant selection.
69
+ - `membershipModel?`: `string | undefined` (default: `'TenantMember'`) — Mongoose model name for the membership collection.
70
+ - `adminBypass?`: `boolean | undefined` (default: `true`) — Whether system admins (RoleEnum.ADMIN) bypass the membership check.
71
+ - `roleHierarchy?`: `Record<string, number> | undefined` (default: `{ member: 1, manager: 2, owner: 3 }`) — Custom role hierarchy for tenant membership roles.
72
+ - `cacheTtlMs?`: `number | undefined` (default: `30000 (30 seconds)`) — TTL in milliseconds for the tenant guard's in-memory membership cache.
73
73
 
74
74
  ### IErrorCode
75
75
 
76
76
  - `additionalErrorRegistry?`: `Record<string, { code: string; message: string; translations: { [locale: stri...` — Additional error registry to merge with core LTNS_* errors
77
- - `autoRegister?`: `boolean` (default: `true`) — Automatically register the ErrorCodeModule in CoreModule
77
+ - `autoRegister?`: `boolean | undefined` (default: `true`) — Automatically register the ErrorCodeModule in CoreModule
78
78
 
79
79
  ### IJwt
80
80
 
81
- - `privateKey?`: `string` — Private key
82
- - `publicKey?`: `string` — Public key
83
- - `secret?`: `string` — Secret to encrypt the JWT
84
- - `secretOrKeyProvider?`: `(request: Record<string, any>, rawJwtToken: string, done: (err: any, secret: ...` — JWT Provider
85
- - `secretOrPrivateKey?`: `string` — Alias of secret (for backwards compatibility)
86
- - `signInOptions?`: `JwtSignOptions` — SignIn Options like expiresIn
81
+ - `privateKey?`: `string | undefined` — Private key
82
+ - `publicKey?`: `string | undefined` — Public key
83
+ - `secret?`: `string | undefined` — Secret to encrypt the JWT
84
+ - `secretOrKeyProvider?`: `((request: Record<string, any>, rawJwtToken: string, done: (err: any, secret:...` — JWT Provider
85
+ - `secretOrPrivateKey?`: `string | undefined` — Alias of secret (for backwards compatibility)
86
+ - `signInOptions?`: `JwtSignOptions | undefined` — SignIn Options like expiresIn
87
87
 
88
88
  ### ICookiesConfig
89
89
 
90
- - `enabled?`: `boolean` (default: `true`) — Whether cookies are enabled.
91
- - `exposeTokenInBody?`: `boolean` (default: `false`) — Whether to include the session token in the response body when cookies are enabled.
90
+ - `enabled?`: `boolean | undefined` (default: `true`) — Whether cookies are enabled.
91
+ - `exposeTokenInBody?`: `boolean | undefined` (default: `false`) — Whether to include the session token in the response body when cookies are enabled.
92
92
 
93
93
  ### ICorsConfig
94
94
 
95
- - `allowAll?`: `boolean` (default: `false`) — Allow all origins by mirroring the request Origin header back.
96
- - `allowedOrigins?`: `string[]` — Additional allowed origins beyond `appUrl` and `baseUrl`.
97
- - `deriveAppUrl?`: `boolean` (default: `true`) — Whether `appUrl` may be auto-derived from `baseUrl` when it is not set explicitly.
98
- - `enabled?`: `boolean` (default: `true`) — Whether CORS is enabled.
95
+ - `allowAll?`: `boolean | undefined` (default: `false`) — Allow all origins by mirroring the request Origin header back.
96
+ - `allowedOrigins?`: `string[] | undefined` — Additional allowed origins beyond `appUrl` and `baseUrl`.
97
+ - `deriveAppUrl?`: `boolean | undefined` (default: `true`) — Whether `appUrl` may be auto-derived from `baseUrl` when it is not set explicitly.
98
+ - `enabled?`: `boolean | undefined` (default: `true`) — Whether CORS is enabled.
99
99
 
100
100
  ### IAi
101
101
 
102
- - `allowedBaseUrlHosts?`: `string[]` — Optional SSRF allowlist for connection base URLs. When set (non-empty), the
103
- - `audit?`: `boolean` (default: `false`) — Persist an audit record (`aiInteractions`) for every prompt run (admin-readable).
102
+ - `allowedBaseUrlHosts?`: `string[] | undefined` — Optional SSRF allowlist for connection base URLs. When set (non-empty), the
103
+ - `audit?`: `boolean | undefined` (default: `false`) — Persist an audit record (`aiInteractions`) for every prompt run (admin-readable).
104
104
  - `budget?`: `{ period?: "day" | "month" | "none"; tenant?: { maxPrompts?: number; maxToken...` — Token/prompt budgets for AI prompts, enforced before a run (HTTP 429 + translated
105
- - `confirmation?`: `{ mutating?: { default?: boolean; enforced?: boolean; }; }` — Confirmation policy for mutating tool actions (create/update/delete).
106
- - `documentation?`: `string` — System documentation injected into the system prompt to inform the LLM
107
- - `defaultConnection?`: `IAiDefaultConnection` — Optional one-time seed for a default connection (see {@link IAiDefaultConnection}).
108
- - `defaultMode?`: `"auto" | "plan"` (default: `'auto'`) — Default execution mode when the client does not specify one.
109
- - `enabled?`: `boolean` — Explicitly disable while keeping the config (default: enabled when present).
110
- - `encryptionSecret?`: `string` — Pass-phrase used to derive the AES-256-GCM key for encrypting connection API
111
- - `contextWindow?`: `number` (default: `8192`) — Fallback total context window (input + output tokens) used to budget the
112
- - `claudeCli?`: `{ bin?: string; extraArgs?: string[]; maxBudgetUsd?: number; }` — Optional config for the `ClaudeCliProvider` (LLM backend that invokes a local
113
- - `compaction?`: `boolean` (default: `true`) — LLM-driven context compaction: when a session would overflow the connection's
114
- - `deferToolSchemas?`: `boolean` (default: `false`) — Defer the parameter schemas of tools out of the system prompt. With many tools
115
- - `maxIterations?`: `number` (default: `5`) — Maximum number of agent-loop iterations (tool round-trips).
116
- - `maxToolResultChars?`: `number` (default: `12000`) — Maximum characters of a tool-results payload fed back to the model.
117
- - `promptLearning?`: `{ autoApply?: boolean; enabled?: boolean; minOccurrences?: number; }` — Governed self-improvement loop for the system prompt. The orchestrator records
118
- - `mcp?`: `boolean | { enabled?: boolean; oauth?: boolean; oauthSecret?: string; }` (default: `false`) — Expose the tool registry as an MCP server at `/ai/mcp` (Streamable HTTP) for
119
- - `rateLimit?`: `IAiRateLimit` — Rate limiting for prompts.
120
- - `systemPrompt?`: `string` — Base system prompt prepended to every conversation.
105
+ - `confirmation?`: `{ mutating?: { default?: boolean; enforced?: boolean; }; } | undefined` — Confirmation policy for mutating tool actions (create/update/delete).
106
+ - `documentation?`: `string | undefined` — System documentation injected into the system prompt to inform the LLM
107
+ - `defaultConnection?`: `IAiDefaultConnection | undefined` — Optional one-time seed for a default connection (see {@link IAiDefaultConnection}).
108
+ - `defaultMode?`: `"auto" | "plan" | undefined` (default: `'auto'`) — Default execution mode when the client does not specify one.
109
+ - `enabled?`: `boolean | undefined` — Explicitly disable while keeping the config (default: enabled when present).
110
+ - `encryptionSecret?`: `string | undefined` — Pass-phrase used to derive the AES-256-GCM key for encrypting connection API
111
+ - `contextWindow?`: `number | undefined` (default: `8192`) — Fallback total context window (input + output tokens) used to budget the
112
+ - `claudeCli?`: `{ bin?: string; extraArgs?: string[]; maxBudgetUsd?: number; } | undefined` — Optional config for the `ClaudeCliProvider` (LLM backend that invokes a local
113
+ - `compaction?`: `boolean | undefined` (default: `true`) — LLM-driven context compaction: when a session would overflow the connection's
114
+ - `deferToolSchemas?`: `boolean | undefined` (default: `false`) — Defer the parameter schemas of tools out of the system prompt. With many tools
115
+ - `maxIterations?`: `number | undefined` (default: `5`) — Maximum number of agent-loop iterations (tool round-trips).
116
+ - `maxToolResultChars?`: `number | undefined` (default: `12000`) — Maximum characters of a tool-results payload fed back to the model.
117
+ - `promptLearning?`: `{ autoApply?: boolean; enabled?: boolean; minOccurrences?: number; } | undefined` — Governed self-improvement loop for the system prompt. The orchestrator records
118
+ - `mcp?`: `boolean | { enabled?: boolean; oauth?: boolean; oauthSecret?: string; } | und...` (default: `false`) — Expose the tool registry as an MCP server at `/ai/mcp` (Streamable HTTP) for
119
+ - `rateLimit?`: `IAiRateLimit | undefined` — Rate limiting for prompts.
120
+ - `systemPrompt?`: `string | undefined` — Base system prompt prepended to every conversation.
121
121
 
122
122
  ### IAiRateLimit
123
123
 
124
- - `enabled?`: `boolean` — Explicitly disable while keeping the config (default: enabled when present).
125
- - `max?`: `number` (default: `20`) — Maximum number of prompts per window per user.
126
- - `windowSeconds?`: `number` (default: `60`) — Window length in seconds.
124
+ - `enabled?`: `boolean | undefined` — Explicitly disable while keeping the config (default: enabled when present).
125
+ - `max?`: `number | undefined` (default: `20`) — Maximum number of prompts per window per user.
126
+ - `windowSeconds?`: `number | undefined` (default: `60`) — Window length in seconds.
127
127
 
128
128
  ### IAiDefaultConnection
129
129
 
130
- - `apiKey?`: `string` — Inline plaintext API key (encrypted on seed). Prefer `apiKeyEnv` instead.
131
- - `apiKeyEnv?`: `string` — Name of an environment variable holding the API key (e.g. 'AI_API_KEY').
130
+ - `apiKey?`: `string | undefined` — Inline plaintext API key (encrypted on seed). Prefer `apiKeyEnv` instead.
131
+ - `apiKeyEnv?`: `string | undefined` — Name of an environment variable holding the API key (e.g. 'AI_API_KEY').
132
132
  - `baseUrl`: `string` — Base URL of the OpenAI-compatible endpoint.
133
- - `capabilities?`: `string[]` — Capability tags (free-form, e.g. 'analysis', 'vision').
134
- - `defaultMaxTokens?`: `number` — Default maximum number of tokens for completions.
135
- - `defaultTemperature?`: `number` — Default sampling temperature.
136
- - `description?`: `string` — Human-readable description.
133
+ - `capabilities?`: `string[] | undefined` — Capability tags (free-form, e.g. 'analysis', 'vision').
134
+ - `defaultMaxTokens?`: `number | undefined` — Default maximum number of tokens for completions.
135
+ - `defaultTemperature?`: `number | undefined` — Default sampling temperature.
136
+ - `description?`: `string | undefined` — Human-readable description.
137
137
  - `model`: `string` — Model id sent to the backend (e.g. 'gpt-oss-120b').
138
138
  - `name`: `string` — Human-readable connection name.
139
- - `providerType?`: `string` — Provider type (default 'openai-compatible').
140
- - `supportsJsonResponse?`: `boolean` — Native JSON / structured-output support. Omit to auto-detect by probing the
141
- - `supportsNativeTools?`: `boolean` — Native function/tool-calling support. Omit to auto-detect by probing the
142
- - `supportsVision?`: `boolean` — Whether the model supports image input.
139
+ - `providerType?`: `string | undefined` — Provider type (default 'openai-compatible').
140
+ - `supportsJsonResponse?`: `boolean | undefined` — Native JSON / structured-output support. Omit to auto-detect by probing the
141
+ - `supportsNativeTools?`: `boolean | undefined` — Native function/tool-calling support. Omit to auto-detect by probing the
142
+ - `supportsVision?`: `boolean | undefined` — Whether the model supports image input.
143
143
 
144
144
  ### ICoreModuleOverrides
145
145
 
146
146
  - `ai?`: `{ budgetService?: Type<any>; connectionResolver?: Type<any>; connectionServic...` — Override AI module collaborators with project-specific subclasses.
147
- - `betterAuth?`: `{ controller?: Type<any>; resolver?: Type<any>; }` — Override BetterAuth controller and/or resolver.
148
- - `errorCode?`: `{ controller?: Type<any>; service?: Type<any>; }` — Override ErrorCode controller and/or service.
147
+ - `betterAuth?`: `{ controller?: Type<any>; resolver?: Type<any>; } | undefined` — Override BetterAuth controller and/or resolver.
148
+ - `errorCode?`: `{ controller?: Type<any>; service?: Type<any>; } | undefined` — Override ErrorCode controller and/or service.
149
149
 
150
150
  ### IBetterAuthPasskeyConfig
151
151
 
152
- - `authenticatorAttachment?`: `"cross-platform" | "platform"` (default: `undefined (both allowed)`) — Authenticator attachment preference.
153
- - `challengeStorage?`: `"cookie" | "database"` (default: `'database'`) — Where to store WebAuthn challenges.
154
- - `challengeTtlSeconds?`: `number` (default: `300 (5 minutes)`) — TTL in seconds for database-stored challenges.
155
- - `enabled?`: `boolean` (default: `true (when config block is present)`) — Whether passkey authentication is enabled.
156
- - `origin?`: `string` — Origin URL for WebAuthn.
157
- - `residentKey?`: `"discouraged" | "preferred" | "required"` (default: `'preferred'`) — Resident key (discoverable credential) requirement.
158
- - `rpId?`: `string` — Relying Party ID (usually the domain without protocol).
159
- - `rpName?`: `string` — Relying Party Name (displayed to users)
160
- - `userVerification?`: `"discouraged" | "preferred" | "required"` (default: `'preferred'`) — User verification requirement.
161
- - `webAuthnChallengeCookie?`: `string` (default: `'better-auth-passkey'`) — Custom cookie name for WebAuthn challenge storage.
152
+ - `authenticatorAttachment?`: `"cross-platform" | "platform" | undefined` (default: `undefined (both allowed)`) — Authenticator attachment preference.
153
+ - `challengeStorage?`: `"cookie" | "database" | undefined` (default: `'database'`) — Where to store WebAuthn challenges.
154
+ - `challengeTtlSeconds?`: `number | undefined` (default: `300 (5 minutes)`) — TTL in seconds for database-stored challenges.
155
+ - `enabled?`: `boolean | undefined` (default: `true (when config block is present)`) — Whether passkey authentication is enabled.
156
+ - `origin?`: `string | undefined` — Origin URL for WebAuthn.
157
+ - `residentKey?`: `"discouraged" | "preferred" | "required" | undefined` (default: `'preferred'`) — Resident key (discoverable credential) requirement.
158
+ - `rpId?`: `string | undefined` — Relying Party ID (usually the domain without protocol).
159
+ - `rpName?`: `string | undefined` — Relying Party Name (displayed to users)
160
+ - `userVerification?`: `"discouraged" | "preferred" | "required" | undefined` (default: `'preferred'`) — User verification requirement.
161
+ - `webAuthnChallengeCookie?`: `string | undefined` (default: `'better-auth-passkey'`) — Custom cookie name for WebAuthn challenge storage.
162
162
 
163
163
  ### IBetterAuthTwoFactorConfig
164
164
 
165
- - `appName?`: `string` (default: `'Nest Server'`) — App name shown in authenticator apps.
166
- - `enabled?`: `boolean` (default: `true (enabled by default when BetterAuth is active)`) — Whether 2FA is enabled.
165
+ - `appName?`: `string | undefined` (default: `'Nest Server'`) — App name shown in authenticator apps.
166
+ - `enabled?`: `boolean | undefined` (default: `true (enabled by default when BetterAuth is active)`) — Whether 2FA is enabled.
167
167
 
168
168
  ### IBetterAuthJwtConfig
169
169
 
170
- - `enabled?`: `boolean` (default: `true (enabled by default when BetterAuth is active)`) — Whether JWT plugin is enabled.
171
- - `expiresIn?`: `string` (default: `'15m'`) — JWT expiration time
170
+ - `enabled?`: `boolean | undefined` (default: `true (enabled by default when BetterAuth is active)`) — Whether JWT plugin is enabled.
171
+ - `expiresIn?`: `string | undefined` (default: `'15m'`) — JWT expiration time
172
172
 
173
173
  ### IBetterAuthEmailVerificationConfig
174
174
 
175
- - `autoSignInAfterVerification?`: `boolean` (default: `true`) — Whether to automatically sign in the user after email verification.
176
- - `brevoTemplateId?`: `number` (default: `undefined (uses SMTP/EJS templates)`) — Brevo template ID for verification emails.
177
- - `callbackURL?`: `string` (default: `undefined (backend-handled verification)`) — Frontend callback URL for email verification.
178
- - `enabled?`: `boolean` (default: `true (enabled by default when BetterAuth is active)`) — Whether email verification is enabled.
179
- - `expiresIn?`: `number` (default: `86400 (24 hours)`) — Time in seconds until the verification link expires.
180
- - `locale?`: `string` (default: `'en'`) — Locale for the verification email template.
181
- - `resendCooldownSeconds?`: `number` (default: `60`) — Cooldown in seconds between resend requests for the same email address.
182
- - `template?`: `string` (default: `'email-verification'`) — Custom template name for the verification email.
175
+ - `autoSignInAfterVerification?`: `boolean | undefined` (default: `true`) — Whether to automatically sign in the user after email verification.
176
+ - `brevoTemplateId?`: `number | undefined` (default: `undefined (uses SMTP/EJS templates)`) — Brevo template ID for verification emails.
177
+ - `callbackURL?`: `string | undefined` (default: `undefined (backend-handled verification)`) — Frontend callback URL for email verification.
178
+ - `enabled?`: `boolean | undefined` (default: `true (enabled by default when BetterAuth is active)`) — Whether email verification is enabled.
179
+ - `expiresIn?`: `number | undefined` (default: `86400 (24 hours)`) — Time in seconds until the verification link expires.
180
+ - `locale?`: `string | undefined` (default: `'en'`) — Locale for the verification email template.
181
+ - `resendCooldownSeconds?`: `number | undefined` (default: `60`) — Cooldown in seconds between resend requests for the same email address.
182
+ - `template?`: `string | undefined` (default: `'email-verification'`) — Custom template name for the verification email.
183
183
 
184
184
  ### IBetterAuthRateLimit
185
185
 
186
- - `enabled?`: `boolean` (default: `false`) — Whether rate limiting is enabled
187
- - `max?`: `number` (default: `10`) — Maximum number of requests within the time window
188
- - `maxEntries?`: `number` (default: `10000`) — Maximum number of entries in the in-memory rate limit store.
189
- - `message?`: `string` — Custom message when rate limit is exceeded
190
- - `skipEndpoints?`: `string[]` — Endpoints to skip rate limiting entirely
191
- - `strictEndpoints?`: `string[]` — Endpoints to apply stricter rate limiting (e.g., sign-in, sign-up)
192
- - `windowSeconds?`: `number` — Time window in seconds
186
+ - `enabled?`: `boolean | undefined` (default: `false`) — Whether rate limiting is enabled
187
+ - `max?`: `number | undefined` (default: `10`) — Maximum number of requests within the time window
188
+ - `maxEntries?`: `number | undefined` (default: `10000`) — Maximum number of entries in the in-memory rate limit store.
189
+ - `message?`: `string | undefined` — Custom message when rate limit is exceeded
190
+ - `skipEndpoints?`: `string[] | undefined` — Endpoints to skip rate limiting entirely
191
+ - `strictEndpoints?`: `string[] | undefined` — Endpoints to apply stricter rate limiting (e.g., sign-in, sign-up)
192
+ - `windowSeconds?`: `number | undefined` — Time window in seconds
193
193
 
194
194
  ### IBetterAuthSignUpChecksConfig
195
195
 
196
- - `enabled?`: `boolean` (default: `true (enabled by default when BetterAuth is active)`) — Whether sign-up checks are enabled.
197
- - `requiredFields?`: `string[]` (default: `['termsAndPrivacyAccepted']`) — Fields that must be provided and truthy during sign-up.
196
+ - `enabled?`: `boolean | undefined` (default: `true (enabled by default when BetterAuth is active)`) — Whether sign-up checks are enabled.
197
+ - `requiredFields?`: `string[] | undefined` (default: `['termsAndPrivacyAccepted']`) — Fields that must be provided and truthy during sign-up.
198
198
 
199
199
  ### IBetterAuthUserField
200
200
 
201
201
  - `defaultValue?`: `unknown` — Default value for the field
202
- - `fieldName?`: `string` — Database field name (if different from key)
203
- - `input?`: `boolean` (default: `true (Better-Auth default when omitted)`) — Whether a client may supply this field's value via Better-Auth's native input parsing
204
- - `required?`: `boolean` — Whether this field is required
202
+ - `fieldName?`: `string | undefined` — Database field name (if different from key)
203
+ - `input?`: `boolean | undefined` (default: `true (Better-Auth default when omitted)`) — Whether a client may supply this field's value via Better-Auth's native input parsing
204
+ - `required?`: `boolean | undefined` — Whether this field is required
205
205
  - `type`: `BetterAuthFieldType` — Field type
206
206
 
207
207
  ### ServiceOptions
208
208
 
209
- - `checkRights?`: `boolean`
210
- - `collation?`: `CollationOptions`
211
- - `create?`: `boolean`
212
- - `currentUser?`: `{ [key: string]: any; id: string; roles?: string[]; }`
213
- - `fieldSelection?`: `FieldSelection`
214
- - `force?`: `boolean`
215
- - `inputType?`: `new (...params: any[]) => any`
216
- - `outputType?`: `new (...params: any[]) => any`
217
- - `populate?`: `string | PopulateOptions | (string | PopulateOptions)[]`
218
- - `prepareInput?`: `PrepareInputOptions`
219
- - `prepareOutput?`: `PrepareOutputOptions`
209
+ - `checkRights?`: `boolean | undefined`
210
+ - `collation?`: `CollationOptions | undefined`
211
+ - `create?`: `boolean | undefined`
212
+ - `currentUser?`: `{ [key: string]: any; id: string; roles?: string[]; } | undefined`
213
+ - `fieldSelection?`: `FieldSelection | undefined`
214
+ - `force?`: `boolean | undefined`
215
+ - `inputType?`: `(new (...params: any[]) => any) | undefined`
216
+ - `outputType?`: `(new (...params: any[]) => any) | undefined`
217
+ - `populate?`: `string | PopulateOptions | (string | PopulateOptions)[] | undefined`
218
+ - `prepareInput?`: `PrepareInputOptions | undefined`
219
+ - `prepareOutput?`: `PrepareOutputOptions | undefined`
220
220
  - `processFieldSelection?`: `{ dbModel?: Model<any>; ignoreSelections?: boolean; model?: new (...args: any...`
221
- - `pubSub?`: `boolean`
222
- - `raw?`: `boolean`
223
- - `roles?`: `string | string[]`
224
- - `select?`: `string | string[] | Record<string, number | boolean | object>`
225
- - `setCreateOrUpdateUserId?`: `boolean`
221
+ - `pubSub?`: `boolean | undefined`
222
+ - `raw?`: `boolean | undefined`
223
+ - `roles?`: `string | string[] | undefined`
224
+ - `select?`: `string | string[] | Record<string, number | boolean | object> | undefined`
225
+ - `setCreateOrUpdateUserId?`: `boolean | undefined`
226
226
 
227
227
  ## CrudService Methods
228
228
 
@@ -230,44 +230,44 @@ Base class for all services. Located at `src/core/common/services/crud.service.t
230
230
 
231
231
  Generic: `CrudService<Model, CreateInput, UpdateInput>`
232
232
 
233
- - `async aggregate(pipeline: PipelineStage[], serviceOptions?: ServiceOptions & { aggregateOptions?: AggregateOptions; })`: `Promise<T>` — Aggregate
233
+ - `async aggregate(pipeline: PipelineStage[], serviceOptions?: (ServiceOptions & { aggregateOptions?: AggregateOptions; }) | undefined)`: `Promise<T>` — Aggregate
234
234
  - `async aggregateForce(pipeline: PipelineStage[], serviceOptions?: ServiceOptions)`: `Promise<T>` — Aggregate without checks or restrictions
235
235
  - `async aggregateRaw(pipeline: PipelineStage[], serviceOptions?: ServiceOptions)`: `Promise<T>` — Aggregate without checks, restrictions or preparations
236
- - `async create(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Create item
236
+ - `async create(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Create item
237
237
  - `async createForce(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Create item without checks or restrictions
238
238
  - `async createRaw(input: PlainObject<CreateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Create item without checks, restrictions or preparations
239
239
  - `distinct(property: string)`: `Promise<string[]>` — Get distinct values of a property
240
- - `async get(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Get item by ID
240
+ - `async get(id: string, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Get item by ID
241
241
  - `async getForce(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Get item by ID without checks or restrictions
242
242
  - `async getRaw(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Get item by ID without checks, restrictions or preparations
243
- - `async find(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model[]>` — Get items via filter
243
+ - `async find(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions | undefined)`: `Promise<Model[]>` — Get items via filter
244
244
  - `async findForce(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model[]>` — Get items via filter without checks or restrictions
245
245
  - `async findRaw(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model[]>` — Get items via filter without checks, restrictions or preparations
246
- - `async findAndCount(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<{ items: Model[]; pagination: PaginationInfo; totalCount: number; }>` — Get items and total count via filter
246
+ - `async findAndCount(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions | undefined)`: `Promise<{ items: Model[]; pagination: PaginationInfo; totalCount: number; }>` — Get items and total count via filter
247
247
  - `async findAndCountForce(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<{ items: Model[]; pagination: PaginationInfo; totalCount: number; }>` — Get items and total count via filter without checks or restrictions
248
248
  - `async findAndCountRaw(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<{ items: Model[]; pagination: PaginationInfo; totalCount: number; }>` — Get items and total count via filter without checks, restrictions or preparations
249
- - `async findAndUpdate(filter: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., update: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model[]>` — Find and update
249
+ - `async findAndUpdate(filter: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., update: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model[]>` — Find and update
250
250
  - `async findAndUpdateForce(filter: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., update: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model[]>` — Find and update without checks or restrictions
251
251
  - `async findAndUpdateRaw(filter: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., update: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model[]>` — Find and update without checks, restrictions or preparations
252
- - `async findOne(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; }, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Find one item via filter
252
+ - `async findOne(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; }..., serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Find one item via filter
253
253
  - `async findOneForce(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model>` — Find one item via filter without checks or restrictions
254
254
  - `async findOneRaw(filter?: FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryOptions; s..., serviceOptions?: ServiceOptions)`: `Promise<Model>` — Find one item via filter without checks, restrictions or preparations
255
255
  - `getModel()`: `MongooseModel<Document<Types.ObjectId, any, any, Record<string, any>, {}> & M...` — Get service model to process queries directly.
256
256
  - `getNativeCollection(reason: string)`: `Collection<Document>` — Get the native MongoDB Collection, bypassing all Mongoose plugins.
257
257
  - `getNativeConnection(reason: string)`: `Connection` — Get the Mongoose Connection (which provides access to the native MongoDB Db and MongoClient).
258
258
  - `validateNativeAccessReason(reason: string, method: string)`: `void`
259
- - `async read(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions)`: `Promise<Model | Model[]>` — CRUD alias for get or find
260
- - `async readForce(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions)`: `Promise<Model | Model[]>` — CRUD alias for getForce or findForce
261
- - `async readRaw(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions)`: `Promise<Model | Model[]>` — CRUD alias for getRaw or findRaw
262
- - `async update(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Update item via ID
263
- - `async updateForce(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Update item via ID without checks or restrictions
264
- - `async updateRaw(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Update item via ID without checks, restrictions or preparations
265
- - `async delete(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Delete item via ID
266
- - `async deleteForce(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Delete item via ID without checks or restrictions
267
- - `async deleteRaw(id: string, serviceOptions?: ServiceOptions)`: `Promise<Model>` — Delete item via ID without checks, restrictions or preparations
268
- - `async pushToArray(id: string | Types.ObjectId | { id?: any; _id?: any; }, field: string, items: any, options?: { $slice?: number; $position?: number; $sort?: Record<string, 1 | -1>; })`: `Promise<void>` — Append items to an array field without loading the full array.
259
+ - `async read(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions | undefined)`: `Promise<Model | Model[]>` — CRUD alias for get or find
260
+ - `async readForce(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions | undefined)`: `Promise<Model | Model[]>` — CRUD alias for getForce or findForce
261
+ - `async readRaw(input: string | FilterArgs | { filterQuery?: QueryFilter<any>; queryOptions?: QueryO..., serviceOptions?: ServiceOptions | undefined)`: `Promise<Model | Model[]>` — CRUD alias for getRaw or findRaw
262
+ - `async update(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Update item via ID
263
+ - `async updateForce(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Update item via ID without checks or restrictions
264
+ - `async updateRaw(id: string, input: PlainObject<UpdateInput>, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Update item via ID without checks, restrictions or preparations
265
+ - `async delete(id: string, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Delete item via ID
266
+ - `async deleteForce(id: string, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Delete item via ID without checks or restrictions
267
+ - `async deleteRaw(id: string, serviceOptions?: ServiceOptions | undefined)`: `Promise<Model>` — Delete item via ID without checks, restrictions or preparations
268
+ - `async pushToArray(id: string | Types.ObjectId | { id?: any; _id?: any; }, field: string, items: any, options?: { $slice?: number; $position?: number; $sort?: Record<string, 1 | -1>; } | un...)`: `Promise<void>` — Append items to an array field without loading the full array.
269
269
  - `async pullFromArray(id: string | Types.ObjectId | { id?: any; _id?: any; }, field: string, condition: any)`: `Promise<void>` — Remove items from an array field.
270
- - `async processQueryOrDocument(queryOrDocument: Document<Types.ObjectId, any, any, Record<string, any>, {}> | Document<Types...., serviceOptions?: ServiceOptions)`: `Promise<T>` — Execute, populate and map Mongoose query or document(s) with serviceOptions
270
+ - `async processQueryOrDocument(queryOrDocument: Document<Types.ObjectId, any, any, Record<string, any>, {}> | Document<Types...., serviceOptions?: ServiceOptions | undefined)`: `Promise<T>` — Execute, populate and map Mongoose query or document(s) with serviceOptions
271
271
 
272
272
  **Variants:** Each method has three variants:
273
273
  - `method()` — Standard: applies `securityCheck()`, respects permissions