webspresso 0.0.107 → 0.0.109

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 (235) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +3 -3
  3. package/bin/commands/add-esbuild.js +7 -3
  4. package/bin/commands/add-tailwind.js +9 -5
  5. package/bin/commands/build.js +20 -4
  6. package/bin/commands/dev.js +57 -7
  7. package/bin/commands/doctor.js +42 -1
  8. package/bin/commands/favicon-generate.js +10 -3
  9. package/bin/commands/new.js +8 -3
  10. package/bin/commands/start.js +3 -1
  11. package/bin/utils/add-command.js +16 -0
  12. package/core/app.js +52 -8
  13. package/core/applySchema.js +3 -72
  14. package/core/auth/authenticate.js +3 -3
  15. package/core/auth/hash.js +167 -43
  16. package/core/auth/index.js +13 -1
  17. package/core/auth/jwt.js +21 -2
  18. package/core/auth/manager.js +63 -14
  19. package/core/auth/middleware.js +4 -2
  20. package/core/auth/oauth.js +5 -1
  21. package/core/auth/tokens.js +7 -2
  22. package/core/auth/totp.js +42 -6
  23. package/core/auth/user-agent.js +2 -0
  24. package/core/cache/lru.js +10 -0
  25. package/core/cache/tagged-lru.js +4 -0
  26. package/core/client/adapter/datastar.js +1254 -0
  27. package/core/client/api.js +1033 -0
  28. package/core/client/controller.js +1081 -0
  29. package/core/client/debug.js +367 -0
  30. package/core/client/forms.js +1021 -0
  31. package/core/client/fragments.js +738 -0
  32. package/core/client/index.d.ts +40 -0
  33. package/core/client/index.js +347 -0
  34. package/core/client/lite.js +164 -0
  35. package/core/client/server-fragments.js +859 -0
  36. package/core/client/utils.js +144 -0
  37. package/core/compileSchema.js +3 -68
  38. package/core/compression/compressible.js +53 -6
  39. package/core/compression/middleware.js +277 -26
  40. package/core/compression/negotiate.js +31 -12
  41. package/core/context/app-context.js +223 -0
  42. package/core/context/index.js +55 -0
  43. package/core/context/request.js +269 -0
  44. package/core/errors/middleware.js +14 -0
  45. package/core/events/dispatcher.js +177 -15
  46. package/core/events/signal.js +9 -0
  47. package/core/forms/flash.js +136 -102
  48. package/core/health/middleware.js +36 -6
  49. package/core/health/probes.js +12 -2
  50. package/core/http/index.js +10 -1
  51. package/core/http/pipeline.js +558 -368
  52. package/core/index.js +45 -8
  53. package/core/kernel/view.js +41 -10
  54. package/core/metrics/middleware.js +30 -6
  55. package/core/metrics/registry.js +13 -5
  56. package/core/orm/cache/fingerprint.js +32 -11
  57. package/core/orm/cache/layer.js +19 -2
  58. package/core/orm/eager-loader.js +90 -55
  59. package/core/orm/hidden.js +145 -0
  60. package/core/orm/index.js +3 -39
  61. package/core/orm/model.js +54 -3
  62. package/core/orm/query-builder.js +343 -6
  63. package/core/orm/query-filters.js +14 -2
  64. package/core/orm/repository.js +64 -13
  65. package/core/orm/schema-helpers.js +68 -6
  66. package/core/orm/transaction.js +157 -18
  67. package/core/orm/types.js +4 -0
  68. package/core/plugins/index.js +8 -0
  69. package/core/plugins/plugin-manager.js +1098 -0
  70. package/core/queue/adapters/database.js +184 -2
  71. package/core/queue/adapters/memory.js +153 -5
  72. package/core/queue/adapters/redis.js +59 -4
  73. package/core/queue/job.js +14 -1
  74. package/core/queue/manager.js +170 -27
  75. package/core/rate-limit/stores/memory.js +23 -10
  76. package/core/resilience/circuit-breaker.js +61 -22
  77. package/core/schema-cache.js +2 -64
  78. package/core/services/builtins/auth.js +273 -0
  79. package/core/services/builtins/exchange.js +396 -0
  80. package/core/services/builtins/file-manager.js +214 -0
  81. package/core/services/builtins/mail.js +161 -0
  82. package/core/services/builtins/media.js +196 -0
  83. package/core/services/builtins/queue.js +144 -0
  84. package/core/services/builtins/security.js +118 -0
  85. package/core/services/builtins/system.js +219 -0
  86. package/core/services/builtins/webhook.js +110 -0
  87. package/core/services/discovery.js +133 -0
  88. package/core/services/executor.js +651 -0
  89. package/core/services/index.js +113 -5
  90. package/core/services/loader.js +161 -0
  91. package/core/services/memoize.js +408 -0
  92. package/core/services/registry.js +731 -0
  93. package/core/services/validator.js +424 -0
  94. package/core/shutdown/shutdown-manager.js +146 -85
  95. package/core/sse/stream.js +28 -5
  96. package/core/ssr/stream.js +109 -16
  97. package/core/stream/text-stream.js +45 -4
  98. package/core/utils/index.js +110 -0
  99. package/core/utils/timeout.js +12 -1
  100. package/core/validation/apply.js +74 -0
  101. package/core/validation/cache.js +66 -0
  102. package/core/validation/compiler.js +80 -0
  103. package/core/validation/index.js +22 -1
  104. package/index.d.ts +1201 -72
  105. package/index.js +188 -28
  106. package/package.json +75 -26
  107. package/plugins/admin-panel/client/parts/08-record-list.js +717 -70
  108. package/plugins/admin-panel/index.js +19 -8
  109. package/plugins/csrf/index.js +3 -3
  110. package/plugins/data-exchange/export.js +214 -0
  111. package/plugins/data-exchange/import.js +48 -5
  112. package/plugins/data-exchange/index.js +70 -28
  113. package/plugins/data-exchange/preview.js +266 -0
  114. package/plugins/data-exchange/template.js +242 -0
  115. package/plugins/email/admin-component.js +783 -141
  116. package/plugins/email/api-handlers.js +51 -1
  117. package/plugins/email/index.js +5 -0
  118. package/plugins/email/service.js +48 -0
  119. package/plugins/file-manager/admin-component.js +1546 -70
  120. package/plugins/file-manager/api-handlers.js +166 -1
  121. package/plugins/file-manager/core.js +598 -8
  122. package/plugins/file-manager/index.js +8 -0
  123. package/plugins/index.js +7 -0
  124. package/plugins/mcp/auth.js +3 -3
  125. package/plugins/oauth/index.js +36 -3
  126. package/plugins/queue/admin-component.js +1092 -0
  127. package/plugins/queue/api-handlers.js +248 -0
  128. package/plugins/queue/index.js +69 -0
  129. package/plugins/rest-resources/index.js +7 -2
  130. package/plugins/security/admin-component.js +689 -0
  131. package/plugins/security/api-handlers.js +169 -0
  132. package/plugins/security/audit.js +153 -0
  133. package/plugins/security/bruteforce.js +244 -0
  134. package/plugins/security/firewall.js +459 -0
  135. package/plugins/security/headers.js +214 -0
  136. package/plugins/security/honeypot.js +234 -0
  137. package/plugins/security/incident-recorder.js +137 -0
  138. package/plugins/security/index.js +211 -0
  139. package/plugins/seo-checker/analyzer.js +20 -7
  140. package/plugins/upload/index.js +36 -0
  141. package/plugins/webhooks/admin-component.js +702 -175
  142. package/plugins/webhooks/api-handlers.js +75 -1
  143. package/plugins/webhooks/dispatcher.js +290 -11
  144. package/plugins/webhooks/index.js +37 -2
  145. package/plugins/webhooks/sender.js +56 -0
  146. package/plugins/xlsx/engine.js +19 -4
  147. package/src/api/api-loader.js +19 -1
  148. package/src/app-context.js +4 -196
  149. package/src/bundle/index.js +443 -17
  150. package/src/client-runtime/mount.js +9 -2
  151. package/src/dev/api-typegen.js +1300 -0
  152. package/src/dev/banner.js +10 -1
  153. package/src/dev/colors.js +1 -1
  154. package/src/dev/index.js +7 -1
  155. package/src/dev/typegen.js +174 -18
  156. package/src/dev-reload/index.js +1 -1
  157. package/src/discovery/file-route-parser.js +17 -3
  158. package/src/discovery/scan-routes.js +4 -1
  159. package/src/file-router.js +249 -69
  160. package/src/helpers.js +46 -26
  161. package/src/njk-frontmatter.js +30 -4
  162. package/src/plugin-manager.js +5 -1086
  163. package/src/routing/cascading.js +26 -8
  164. package/src/routing/mount-discovered-routes.js +69 -0
  165. package/src/server.js +238 -64
  166. package/src/services/builtins/auth.js +2 -273
  167. package/src/services/builtins/exchange.js +2 -229
  168. package/src/services/builtins/file-manager.js +2 -178
  169. package/src/services/builtins/mail.js +2 -134
  170. package/src/services/builtins/media.js +2 -196
  171. package/src/services/builtins/system.js +2 -219
  172. package/src/services/discovery.js +2 -133
  173. package/src/services/executor.js +2 -575
  174. package/src/services/index.js +4 -109
  175. package/src/services/loader.js +1 -119
  176. package/src/services/memoize.js +2 -408
  177. package/src/services/registry.js +1 -711
  178. package/src/services/validator.js +2 -424
  179. package/.agents/ADMIN.md +0 -426
  180. package/.agents/AGENTS.md +0 -93
  181. package/.agents/ARCHITECTURE.md +0 -163
  182. package/.agents/AUTH.md +0 -581
  183. package/.agents/CACHE.md +0 -147
  184. package/.agents/CLI.md +0 -649
  185. package/.agents/COMPRESSION.md +0 -59
  186. package/.agents/CONVENTIONS.md +0 -50
  187. package/.agents/EARLY_HINTS.md +0 -120
  188. package/.agents/EMAIL.md +0 -223
  189. package/.agents/ERRORS.md +0 -260
  190. package/.agents/EVENTS.md +0 -179
  191. package/.agents/FLAGS.md +0 -118
  192. package/.agents/HEALTH.md +0 -118
  193. package/.agents/LIMITS.md +0 -109
  194. package/.agents/LOGGING.md +0 -93
  195. package/.agents/MCP.md +0 -103
  196. package/.agents/METRICS.md +0 -127
  197. package/.agents/MIGRATION_JOBS.md +0 -95
  198. package/.agents/ORM.md +0 -626
  199. package/.agents/PLUGINS.md +0 -729
  200. package/.agents/QUEUE.md +0 -290
  201. package/.agents/RATE_LIMIT.md +0 -147
  202. package/.agents/REALTIME.md +0 -213
  203. package/.agents/RESILIENCE.md +0 -235
  204. package/.agents/ROUTING.md +0 -605
  205. package/.agents/SCALE_OUT.md +0 -109
  206. package/.agents/SECRETS.md +0 -117
  207. package/.agents/SERVICES.md +0 -341
  208. package/.agents/SHUTDOWN.md +0 -67
  209. package/.agents/STREAMING.md +0 -108
  210. package/.agents/WORKFLOW.md +0 -27
  211. package/.agents/internal/DOCUMENTATION_REVIEW.md +0 -485
  212. package/.agents/internal/TECHNICAL_REVIEW.md +0 -428
  213. package/.agents/skills/webspresso-admin-and-plugins/SKILL.md +0 -122
  214. package/.agents/skills/webspresso-framework/SKILL.md +0 -88
  215. package/.agents/skills/webspresso-orm-and-database/SKILL.md +0 -118
  216. package/.agents/skills/webspresso-routing-and-api/SKILL.md +0 -114
  217. package/.agents/skills/webspresso-services/SKILL.md +0 -101
  218. package/.cursorrules +0 -14
  219. package/AGENTS.md +0 -200
  220. package/CLAUDE.md +0 -54
  221. package/core/kernel/run-demo.js +0 -58
  222. package/core/utils/array.js +0 -12
  223. package/core/utils/base64url.js +0 -8
  224. package/core/utils/ensure-leading-slash.js +0 -6
  225. package/core/utils/escape-html.js +0 -7
  226. package/core/utils/escape-regexp.js +0 -7
  227. package/core/utils/get-client-ip.js +0 -6
  228. package/core/utils/hmac.js +0 -6
  229. package/core/utils/random.js +0 -9
  230. package/core/utils/safe-compare.js +0 -3
  231. package/core/utils/sha256.js +0 -6
  232. package/core/utils/strip-trailing-slash.js +0 -6
  233. package/core/utils/walk.js +0 -7
  234. package/plugins/admin-panel/styles.js +0 -9
  235. package/plugins/data-exchange/export-xlsx.js +0 -119
package/index.d.ts CHANGED
@@ -52,6 +52,30 @@ export interface CreateAppOptions {
52
52
  };
53
53
  /** Trust proxy configuration (default: 1) */
54
54
  trustProxy?: boolean | number | string;
55
+ /** Hardened query parser configuration: 'simple' | false | Function | { depth?: number; parameterLimit?: number; arrayLimit?: number; allowDots?: boolean } */
56
+ queryParser?: 'simple' | 'extended' | boolean | ((str: string) => unknown) | {
57
+ depth?: number;
58
+ parameterLimit?: number;
59
+ arrayLimit?: number;
60
+ allowDots?: boolean;
61
+ };
62
+ /** Cookie / session signing secret(s) for cookie-parser, signed cookies, and flash messages */
63
+ secret?: string | string[];
64
+ cookieSecret?: string | string[];
65
+ session?: {
66
+ secret?: string | string[];
67
+ [key: string]: unknown;
68
+ };
69
+ cookies?: {
70
+ secret?: string | string[];
71
+ [key: string]: unknown;
72
+ };
73
+ /** Cookie/session-backed flash messages and old input options */
74
+ flash?: {
75
+ cookieName?: string;
76
+ signed?: boolean;
77
+ secret?: string | string[];
78
+ };
55
79
  /**
56
80
  * Custom 404 / 500 / 503 handlers. File-based route errors are forwarded with `next(err)` and hit `serverError` / `timeout`.
57
81
  * When `serverError` / `timeout` is a template path, it is not used for paths under `/api` (default JSON instead).
@@ -76,6 +100,12 @@ export interface CreateAppOptions {
76
100
  };
77
101
  auth?: unknown;
78
102
  db?: DatabaseInstance | null;
103
+ /** Background Job Queue: QueueManager instance, options object, or false to disable */
104
+ queue?: QueueManager | Record<string, unknown> | boolean;
105
+ /** Directory path to auto-discover job handlers (defaults to 'jobs' or 'src/jobs') */
106
+ jobsDir?: string;
107
+ /** Whether to start background queue worker automatically (default: true, false in test env) */
108
+ queueAutoStart?: boolean;
79
109
  /** HTTP response compression options */
80
110
  compression?: boolean | CompressionOptions;
81
111
  /** HTTP 103 Early Hints options (preloads CSS/JS before SSR finish) */
@@ -119,6 +149,12 @@ export interface CreateAppOptions {
119
149
  metrics?: boolean | MetricsConfig;
120
150
  cache?: boolean | LruCacheConfig;
121
151
  trustProxy?: boolean | number | string;
152
+ queryParser?: 'simple' | 'extended' | boolean | ((str: string) => unknown) | {
153
+ depth?: number;
154
+ parameterLimit?: number;
155
+ arrayLimit?: number;
156
+ allowDots?: boolean;
157
+ };
122
158
  [key: string]: unknown;
123
159
  };
124
160
  /** Opt-in Alpine / swup assets under `/__webspresso/client-runtime/*`. Env: WEBSPRESSO_ALPINE, WEBSPRESSO_SWUP. */
@@ -414,7 +450,7 @@ export function defineService<TInput = unknown, TOutput = unknown>(
414
450
  definition: ServiceDefinition<TInput, TOutput> | ServiceHandler<TInput, TOutput>
415
451
  ): ServiceDefinition<TInput, TOutput>;
416
452
 
417
- export const service: typeof defineService;
453
+ export declare const service: typeof defineService;
418
454
 
419
455
  export interface MemoizeOptions {
420
456
  ttl?: string | number | boolean;
@@ -492,6 +528,22 @@ export function createExchangeServices(options?: {
492
528
  db?: unknown;
493
529
  }): Record<string, ServiceDefinition>;
494
530
 
531
+ export function createWebhookServices(options?: {
532
+ dispatcher: unknown;
533
+ }): Record<string, ServiceDefinition>;
534
+
535
+ export function createQueueServices(options?: {
536
+ queueManager?: unknown;
537
+ queue?: unknown;
538
+ }): Record<string, ServiceDefinition>;
539
+
540
+ export function createSecurityServices(options?: {
541
+ firewall: unknown;
542
+ incidentRecorder?: unknown;
543
+ pluginOptions?: unknown;
544
+ app?: unknown;
545
+ }): Record<string, ServiceDefinition>;
546
+
495
547
  export function validateServiceInput(
496
548
  schema: unknown,
497
549
  input: unknown,
@@ -541,6 +593,9 @@ export interface ShutdownOptions {
541
593
  signals?: string[];
542
594
  logger?: unknown;
543
595
  exitOnSignal?: boolean;
596
+ parallel?: boolean;
597
+ parallelDisposers?: boolean;
598
+ parallelHooks?: boolean;
544
599
  }
545
600
 
546
601
  export interface EarlyHintLink {
@@ -585,6 +640,7 @@ export class ShutdownManager {
585
640
  readonly isClosed: boolean;
586
641
  mode: 'graceful' | 'force';
587
642
  timeout: number;
643
+ parallel: boolean;
588
644
  onShutdown(fn: () => Promise<void> | void): this;
589
645
  registerDisposer(nameOrFn: string | (() => Promise<void> | void), maybeFn?: () => Promise<void> | void): this;
590
646
  registerAdapter(adapter: ServerAdapter): this;
@@ -714,6 +770,7 @@ export class HonoHttpAdapter extends HttpAdapter {
714
770
  export function createHonoHttpAdapter(app?: unknown, options?: Record<string, unknown>): HonoHttpAdapter;
715
771
 
716
772
  export function runMiddlewares(middlewares: unknown[], req: unknown, res: unknown): Promise<void>;
773
+ export function createPipelineRunner(middlewares?: unknown[]): (req: unknown, res: unknown) => Promise<void>;
717
774
  export function enrichRouteError(err: unknown, descriptor: RouteDescriptor | Record<string, unknown>, req: unknown): unknown;
718
775
  export function executeApiPipeline(params: {
719
776
  descriptor: RouteDescriptor | Record<string, unknown>;
@@ -840,6 +897,14 @@ export namespace compression {
840
897
  export function appendVary(res: unknown, field: string): void;
841
898
  }
842
899
 
900
+ export const supportsBrotli: typeof compression.supportsBrotli;
901
+ export const getDefaultSupportedEncodings: typeof compression.getDefaultSupportedEncodings;
902
+ export const parseAcceptEncoding: typeof compression.parseAcceptEncoding;
903
+ export const selectEncoding: typeof compression.selectEncoding;
904
+ export const isCompressible: typeof compression.isCompressible;
905
+ export const createCompressionStream: typeof compression.createCompressionStream;
906
+ export const appendVary: typeof compression.appendVary;
907
+
843
908
  export function createEarlyHintsMiddleware(options?: boolean | EarlyHintsOptions): RequestHandler;
844
909
  export function sendEarlyHints(
845
910
  res: unknown,
@@ -863,6 +928,8 @@ export namespace earlyHints {
863
928
  export function createEarlyHintsMiddleware(options?: boolean | EarlyHintsOptions): RequestHandler;
864
929
  }
865
930
 
931
+ export const EXTENSION_AS_MAP: typeof earlyHints.EXTENSION_AS_MAP;
932
+
866
933
  export interface PayloadLimitParserConfig {
867
934
  enabled?: boolean;
868
935
  limit?: string | number;
@@ -909,6 +976,11 @@ export namespace limits {
909
976
  export function setupLimitsMiddleware(app: Application, options?: unknown): unknown;
910
977
  }
911
978
 
979
+ export const DEFAULT_LIMITS: typeof limits.DEFAULT_LIMITS;
980
+ export const matchesPath: typeof limits.matchesPath;
981
+ export const shouldSkipBodyParser: typeof limits.shouldSkipBodyParser;
982
+ export const shouldCaptureRawBody: typeof limits.shouldCaptureRawBody;
983
+
912
984
  export interface HealthCheckConfig {
913
985
  /** Enable or disable health check endpoints (default: true if healthCheck option is provided) */
914
986
  enabled?: boolean;
@@ -932,6 +1004,8 @@ export interface HealthCheckConfig {
932
1004
  checks?: Record<string, (context: unknown) => Promise<unknown> | unknown>;
933
1005
  /** Custom headers to attach to health probe responses */
934
1006
  headers?: Record<string, string>;
1007
+ /** Include pid/nodeVersion/platform and raw dependency error messages (default: true outside production) */
1008
+ exposeDetails?: boolean;
935
1009
  }
936
1010
 
937
1011
  export function normalizeHealthConfig(options?: unknown): unknown;
@@ -951,6 +1025,8 @@ export namespace health {
951
1025
  export function setupHealthMiddleware(app: Application, options?: unknown, context?: unknown): unknown;
952
1026
  }
953
1027
 
1028
+ export const DEFAULT_HEALTH_CONFIG: typeof health.DEFAULT_HEALTH_CONFIG;
1029
+
954
1030
  // --- In-Memory & Tagged LRU Cache Engine ---
955
1031
 
956
1032
  export interface LruCacheConfig {
@@ -966,6 +1042,8 @@ export interface LruCacheConfig {
966
1042
  clone?: boolean;
967
1043
  /** Custom byte sizer function (default: approximateByteSize) */
968
1044
  sizeCalculation?: (value: unknown, key: string) => number;
1045
+ /** Whether to compute and track approximate byte sizes when maxBytes/maxMemoryMb is not set (default: false when byte limit is 0) */
1046
+ trackBytes?: boolean;
969
1047
  /** Callback fired when an entry is evicted, expired, or deleted */
970
1048
  onEvict?: (key: string, value: unknown, reason: 'evict' | 'expire' | 'delete' | 'clear') => void;
971
1049
  }
@@ -976,6 +1054,7 @@ export class LruCache<V = unknown> {
976
1054
  readonly currentBytes: number;
977
1055
  readonly maxBytes: number;
978
1056
  readonly maxEntries: number;
1057
+ readonly trackBytes: boolean;
979
1058
  readonly hits: number;
980
1059
  readonly misses: number;
981
1060
  readonly hitRate: number;
@@ -1005,6 +1084,7 @@ export class TaggedLruCache<V = unknown> {
1005
1084
  readonly currentBytes: number;
1006
1085
  readonly maxBytes: number;
1007
1086
  readonly maxEntries: number;
1087
+ readonly trackBytes: boolean;
1008
1088
  readonly hits: number;
1009
1089
  readonly misses: number;
1010
1090
  readonly hitRate: number;
@@ -1156,6 +1236,8 @@ export interface CircuitBreakerOptions {
1156
1236
  rollingWindow?: number | string;
1157
1237
  rollingWindowMs?: number | string;
1158
1238
  successThreshold?: number;
1239
+ /** Concurrent trial calls allowed in HALF_OPEN (default: successThreshold) */
1240
+ halfOpenMaxCalls?: number;
1159
1241
  resetTimeout?: number | string;
1160
1242
  resetTimeoutMs?: number | string;
1161
1243
  timeout?: number | string;
@@ -1182,7 +1264,7 @@ export interface CircuitBreakerStats {
1182
1264
  lastStateChange: number;
1183
1265
  }
1184
1266
 
1185
- export class CircuitBreaker extends import('events').EventEmitter {
1267
+ export class CircuitBreaker extends EventEmitter {
1186
1268
  readonly name: string;
1187
1269
  readonly failureThreshold: number;
1188
1270
  readonly failureRateThreshold: number | null;
@@ -1250,7 +1332,7 @@ export class CircuitBreakerRegistry {
1250
1332
  clear(): void;
1251
1333
  }
1252
1334
 
1253
- export const circuitBreakerRegistry: CircuitBreakerRegistry;
1335
+ export declare const circuitBreakerRegistry: CircuitBreakerRegistry;
1254
1336
  export function getBreaker(name: string, options?: CircuitBreakerOptions): CircuitBreaker;
1255
1337
 
1256
1338
  export namespace resilience {
@@ -1276,7 +1358,7 @@ export function resolveClientRuntime(options?: {
1276
1358
  };
1277
1359
  }): { alpine: boolean; swup: boolean };
1278
1360
 
1279
- export const CLIENT_RUNTIME_BASE: string;
1361
+ export declare const CLIENT_RUNTIME_BASE: string;
1280
1362
 
1281
1363
  // --- App context ---
1282
1364
 
@@ -1310,14 +1392,20 @@ export function getMailer(): Mailer | null;
1310
1392
 
1311
1393
  export function hasMailer(): boolean;
1312
1394
 
1395
+ export function getQueue(): QueueManager | null;
1396
+
1397
+ export function hasQueue(): boolean;
1398
+
1313
1399
  export function resetAppContext(): void;
1314
1400
 
1315
1401
  export function setAppContext(partial: {
1316
1402
  db?: DatabaseInstance | null;
1403
+ queue?: QueueManager | null;
1317
1404
  shutdownManager?: ShutdownManager | null;
1318
1405
  serviceRegistry?: ServiceRegistry | null;
1319
1406
  events?: any;
1320
1407
  mailer?: Mailer | null;
1408
+ cache?: any;
1321
1409
  }): void;
1322
1410
 
1323
1411
  // --- File router ---
@@ -1383,6 +1471,19 @@ export namespace cascading {
1383
1471
  export function clearCascadingCaches(): void;
1384
1472
  }
1385
1473
 
1474
+ export const getDirectoryChain: typeof cascading.getDirectoryChain;
1475
+ export const templateHasExtends: typeof cascading.templateHasExtends;
1476
+ export const findCascadingMiddlewareFiles: typeof cascading.findCascadingMiddlewareFiles;
1477
+ export const loadCascadingMiddlewares: typeof cascading.loadCascadingMiddlewares;
1478
+ export const runMiddleware: typeof cascading.runMiddleware;
1479
+ export const runMiddlewareChain: typeof cascading.runMiddlewareChain;
1480
+ export const findCascadingLayouts: typeof cascading.findCascadingLayouts;
1481
+ export const executeCascadingLayoutLoads: typeof cascading.executeCascadingLayoutLoads;
1482
+ export const applyCascadingLayouts: typeof cascading.applyCascadingLayouts;
1483
+ export const findNearestErrorBoundary: typeof cascading.findNearestErrorBoundary;
1484
+ export const findNearestLoadingTemplate: typeof cascading.findNearestLoadingTemplate;
1485
+ export const clearCascadingCaches: typeof cascading.clearCascadingCaches;
1486
+
1386
1487
  export function resolveMiddlewares(
1387
1488
  middlewareConfig: unknown[] | null | undefined,
1388
1489
  middlewareRegistry?: Record<string, unknown>
@@ -1488,7 +1589,11 @@ export interface FlashMessages {
1488
1589
  [key: string]: any;
1489
1590
  }
1490
1591
 
1491
- export function createFlashMiddleware(options?: { cookieName?: string }): import('express').RequestHandler;
1592
+ export function createFlashMiddleware(options?: {
1593
+ cookieName?: string;
1594
+ signed?: boolean;
1595
+ secret?: string | string[];
1596
+ }): import('express').RequestHandler;
1492
1597
 
1493
1598
  export function normalizeErrors(errors: any): Record<string, string[]>;
1494
1599
 
@@ -1558,6 +1663,13 @@ export interface EventListenerOptions {
1558
1663
  once?: boolean;
1559
1664
  }
1560
1665
 
1666
+ export interface WaitForOptions {
1667
+ timeout?: number;
1668
+ filter?: (data: any, meta: any) => boolean;
1669
+ signal?: AbortSignal;
1670
+ sender?: any;
1671
+ }
1672
+
1561
1673
  export class EventDispatcher {
1562
1674
  constructor(options?: { queue?: any; maxListeners?: number; logger?: any });
1563
1675
  on(event: string, handler: Function, options?: EventListenerOptions): () => void;
@@ -1569,6 +1681,7 @@ export class EventDispatcher {
1569
1681
  emitParallel(eventOrInstance: string | object, data?: any, options?: { sender?: any }): Promise<Array<{ status: 'fulfilled' | 'rejected'; value?: any; reason?: any }>>;
1570
1682
  emitSerial(eventOrInstance: string | object, data?: any, options?: { sender?: any }): Promise<any[]>;
1571
1683
  emitWaterfall(eventOrInstance: string | object, initialData: any, options?: { sender?: any }): Promise<any>;
1684
+ waitFor(event: string, optionsOrTimeout?: WaitForOptions | number | ((data: any, meta: any) => boolean)): Promise<{ data: any; meta: Record<string, unknown> }>;
1572
1685
  listenAndQueue(event: string, jobName: string, queueOptions?: Record<string, unknown>): () => void;
1573
1686
  bridgeOrm(modelEvents?: any): () => void;
1574
1687
  setQueue(queueManager: any): this;
@@ -1580,7 +1693,7 @@ export class EventDispatcher {
1580
1693
 
1581
1694
  export function createEventDispatcher(options?: { queue?: any; maxListeners?: number; logger?: any }): EventDispatcher;
1582
1695
 
1583
- export const events: EventDispatcher;
1696
+ export declare const events: EventDispatcher;
1584
1697
 
1585
1698
  export class Signal {
1586
1699
  constructor(name: string, dispatcher: EventDispatcher);
@@ -1591,6 +1704,7 @@ export class Signal {
1591
1704
  send(data?: any, options?: { sender?: any }): boolean;
1592
1705
  sendAsync(data?: any, options?: { sender?: any }): Promise<Array<{ status: 'fulfilled' | 'rejected'; value?: any; reason?: any }>>;
1593
1706
  sendSerial(data?: any, options?: { sender?: any }): Promise<any[]>;
1707
+ waitFor(optionsOrTimeout?: WaitForOptions | number | ((data: any, meta: any) => boolean)): Promise<{ data: any; meta: Record<string, unknown> }>;
1594
1708
  }
1595
1709
 
1596
1710
  export function defineSignal(name: string, dispatcher?: EventDispatcher): Signal;
@@ -1683,7 +1797,7 @@ export function pick<T extends object, K extends keyof T>(obj: T | null | undefi
1683
1797
  export function omit<T extends object, K extends keyof T>(obj: T | null | undefined, keys: K[] | K): Omit<T, K>;
1684
1798
  export function deepClone<T>(obj: T): T;
1685
1799
 
1686
- export const DEFAULT_TIMEOUTS: Readonly<{
1800
+ export declare const DEFAULT_TIMEOUTS: Readonly<{
1687
1801
  request: number;
1688
1802
  service: number;
1689
1803
  queue: number;
@@ -1737,7 +1851,7 @@ export function createTimeoutMiddleware(
1737
1851
  options?: { respond?: boolean }
1738
1852
  ): (req: Request, res: Response, next: (err?: unknown) => void) => void;
1739
1853
 
1740
- export const utils: Record<string, unknown>;
1854
+ export declare const utils: Record<string, unknown>;
1741
1855
 
1742
1856
  export class AssetManager {
1743
1857
  constructor(options?: Record<string, unknown>);
@@ -1984,6 +2098,8 @@ export interface RestMetadata {
1984
2098
  enabled?: boolean;
1985
2099
  path?: string;
1986
2100
  allowInclude?: string[];
2101
+ /** Columns accepted on POST/PATCH; when omitted every non-hidden column is writable */
2102
+ writable?: string[];
1987
2103
  }
1988
2104
 
1989
2105
  export interface ScopeOptions {
@@ -2008,7 +2124,7 @@ export type InferModelUpdate<T> = Partial<InferModel<T>>;
2008
2124
  export interface ModelOptions<TSchema = ZodObject<Record<string, ZodTypeAny>>> {
2009
2125
  name: string;
2010
2126
  table: string;
2011
- schema: TSchema | Record<string, any>;
2127
+ schema: TSchema | Record<string, any> | ((ctx: { zdb: Zdb; z: typeof import('zod').z; zod: typeof import('zod').z }) => TSchema | Record<string, any>);
2012
2128
  primaryKey?: string;
2013
2129
  timestamps?: boolean | { createdAt?: string; updatedAt?: string; snakeCase?: boolean };
2014
2130
  softDelete?: boolean | { deletedAt?: string; snakeCase?: boolean };
@@ -2040,6 +2156,8 @@ export interface ModelDefinition<TModel = Record<string, any>> {
2040
2156
  name: string;
2041
2157
  table: string;
2042
2158
  schema: ZodObject<Record<string, ZodTypeAny>>;
2159
+ _insertSchema?: ZodTypeAny;
2160
+ _partialSchema?: ZodTypeAny;
2043
2161
  primaryKey: string;
2044
2162
  relations: Record<string, RelationDefinition>;
2045
2163
  scopes: {
@@ -2096,14 +2214,19 @@ export function isCascadeEnabled(relation: RelationDefinition, operation: 'delet
2096
2214
 
2097
2215
  /** zdb column helpers (id, string, timestamp, …) + `schema()` */
2098
2216
  export type Zdb = Record<string, any> & {
2217
+ z: typeof import('zod').z;
2218
+ zod: typeof import('zod').z;
2219
+ number(options?: any): any;
2220
+ email(options?: any): any;
2099
2221
  schema(shape: Record<string, any>): ZodObject<Record<string, ZodTypeAny>>;
2100
2222
  timestamps(options?: { snakeCase?: boolean; createdAt?: string; updatedAt?: string }): Record<string, any>;
2101
2223
  softDelete(options?: Record<string, any>): any;
2102
2224
  softDeletes(options?: { snakeCase?: boolean; deletedAt?: string }): Record<string, any>;
2103
2225
  };
2104
2226
 
2105
- export const zdb: Zdb;
2106
- export const z: typeof import('zod').z;
2227
+ export declare const zdb: Zdb;
2228
+ export declare const z: typeof import('zod').z;
2229
+ export declare const zod: typeof import('zod').z;
2107
2230
 
2108
2231
  export function createSchemaHelpers(z: typeof import('zod').z): Zdb;
2109
2232
 
@@ -2140,13 +2263,36 @@ export interface SearchOptions {
2140
2263
  }
2141
2264
 
2142
2265
  export interface QueryBuilder<T = Record<string, any>> {
2266
+ select(...columns: (keyof T | string)[]): this;
2267
+ distinct(...columns: (keyof T | string)[]): this;
2143
2268
  where(column: keyof T | string, value: unknown): this;
2144
2269
  where(column: keyof T | string, operator: string, value: unknown): this;
2145
2270
  where(conditions: Partial<T> | Record<string, unknown>): this;
2146
2271
  orWhere(...args: unknown[]): this;
2272
+ whereNot(column: keyof T | string | Partial<T>, value?: unknown): this;
2273
+ orWhereNot(column: keyof T | string | Partial<T>, value?: unknown): this;
2147
2274
  whereIn(column: keyof T | string, values: unknown[]): this;
2148
- whereBetween(column: keyof T | string, range: [unknown, unknown]): this;
2149
- select(...columns: (keyof T | string)[]): this;
2275
+ orWhereIn(column: keyof T | string, values: unknown[]): this;
2276
+ whereNotIn(column: keyof T | string, values: unknown[]): this;
2277
+ orWhereNotIn(column: keyof T | string, values: unknown[]): this;
2278
+ whereNull(column: keyof T | string): this;
2279
+ orWhereNull(column: keyof T | string): this;
2280
+ whereNotNull(column: keyof T | string): this;
2281
+ orWhereNotNull(column: keyof T | string): this;
2282
+ whereBetween(column: keyof T | string, range: [unknown, unknown] | unknown[]): this;
2283
+ orWhereBetween(column: keyof T | string, range: [unknown, unknown] | unknown[]): this;
2284
+ whereNotBetween(column: keyof T | string, range: [unknown, unknown] | unknown[]): this;
2285
+ orWhereNotBetween(column: keyof T | string, range: [unknown, unknown] | unknown[]): this;
2286
+ whereRaw(sql: string, bindings?: unknown[]): this;
2287
+ orWhereRaw(sql: string, bindings?: unknown[]): this;
2288
+ groupBy(...columns: (keyof T | string)[]): this;
2289
+ groupByRaw(sql: string, bindings?: unknown[]): this;
2290
+ having(column: string, value: unknown): this;
2291
+ having(column: string, operator: string, value: unknown): this;
2292
+ orHaving(column: string, value: unknown): this;
2293
+ orHaving(column: string, operator: string, value: unknown): this;
2294
+ havingRaw(sql: string, bindings?: unknown[]): this;
2295
+ orHavingRaw(sql: string, bindings?: unknown[]): this;
2150
2296
  orderBy(column: keyof T | string, direction?: 'asc' | 'desc'): this;
2151
2297
  orderByRaw(sql: string, bindings?: unknown[]): this;
2152
2298
  search(term: string, columns?: string | string[], options?: SearchOptions): this;
@@ -2168,6 +2314,7 @@ export interface QueryBuilder<T = Record<string, any>> {
2168
2314
  find(): Promise<T[]>;
2169
2315
  count(): Promise<number>;
2170
2316
  paginate(page?: number, perPage?: number): Promise<PaginatedResult<T>>;
2317
+ paginate(options: { page?: number; perPage?: number; limit?: number }): Promise<PaginatedResult<T>>;
2171
2318
  exists(): Promise<boolean>;
2172
2319
  clone(): QueryBuilder<T>;
2173
2320
  getWiths(): string[];
@@ -2381,7 +2528,7 @@ export interface DatabaseInstance {
2381
2528
 
2382
2529
  export function createDatabase(config: DatabaseConfig): DatabaseInstance;
2383
2530
  export function createD1Knex(d1Database: unknown, options?: Record<string, unknown>): Knex;
2384
- export const Client_D1: unknown;
2531
+ export declare const Client_D1: unknown;
2385
2532
  export function executeD1Batch(
2386
2533
  d1Database: unknown,
2387
2534
  queriesOrCallback: Array<any> | ((batch: { add(q: any): any; raw(sql: string, bindings?: any[]): any }) => Promise<any> | any)
@@ -2529,7 +2676,7 @@ export function runCloudMigration(knex: unknown, options?: CloudMigrationOptions
2529
2676
 
2530
2677
  export function generateNanoid(options?: { maxLength?: number } | number): string;
2531
2678
 
2532
- export const zodNanoid: ZodTypeAny;
2679
+ export declare const zodNanoid: ZodTypeAny;
2533
2680
 
2534
2681
  export function extendZ(z: typeof import('zod').z): typeof import('zod').z;
2535
2682
 
@@ -2544,14 +2691,14 @@ export function sanitizeForOutput(
2544
2691
 
2545
2692
  // --- ORM: events ---
2546
2693
 
2547
- export const ModelEvents: {
2694
+ export declare const ModelEvents: {
2548
2695
  on(event: string, handler: (...args: unknown[]) => void): void;
2549
2696
  emit(event: string, ...args: unknown[]): void;
2550
2697
  emitAsync?(event: string, ...args: unknown[]): Promise<void>;
2551
2698
  [key: string]: unknown;
2552
2699
  };
2553
2700
 
2554
- export const Hooks: Record<string, string>;
2701
+ export declare const Hooks: Record<string, string>;
2555
2702
 
2556
2703
  export class HookCancellationError extends Error {
2557
2704
  reason: string;
@@ -2579,7 +2726,7 @@ export class QueryComplexityError extends BadRequestError {
2579
2726
  code: string;
2580
2727
  }
2581
2728
 
2582
- export const DEFAULT_QUERY_LIMITS: {
2729
+ export declare const DEFAULT_QUERY_LIMITS: {
2583
2730
  maxLimit: number;
2584
2731
  defaultLimit: number;
2585
2732
  maxIncludes: number;
@@ -2741,7 +2888,91 @@ export function defineLazyPlugin(
2741
2888
 
2742
2889
  export function adminPanelPlugin(options?: AdminPanelPluginOptions): WebspressoPlugin;
2743
2890
 
2744
- export function dataExchangePlugin(options?: Record<string, unknown>): WebspressoPlugin;
2891
+ export interface DataExchangePluginOptions {
2892
+ enabled?: boolean;
2893
+ db?: any;
2894
+ adminPath?: string;
2895
+ maxRows?: number;
2896
+ maxFileBytes?: number;
2897
+ [key: string]: unknown;
2898
+ }
2899
+
2900
+ export function dataExchangePlugin(options?: DataExchangePluginOptions): WebspressoPlugin;
2901
+
2902
+ export interface SitemapDynamicSource {
2903
+ model?: string;
2904
+ query?: (db: any) => Promise<any[]>;
2905
+ urlPattern: string;
2906
+ fields?: Record<string, string>;
2907
+ lastmodField?: string;
2908
+ changefreq?: string;
2909
+ priority?: number;
2910
+ i18n?: boolean;
2911
+ filter?: (record: any) => boolean;
2912
+ transform?: (record: any) => any;
2913
+ }
2914
+
2915
+ export interface SitemapPluginOptions {
2916
+ hostname?: string;
2917
+ exclude?: string[];
2918
+ changefreq?: string;
2919
+ priority?: number;
2920
+ i18n?: boolean;
2921
+ locales?: string[];
2922
+ robots?: boolean;
2923
+ robotsDisallow?: string[];
2924
+ dynamicSources?: SitemapDynamicSource[];
2925
+ db?: any;
2926
+ cacheMaxAge?: number;
2927
+ [key: string]: unknown;
2928
+ }
2929
+
2930
+ export function sitemapPlugin(options?: SitemapPluginOptions): WebspressoPlugin;
2931
+
2932
+ export interface SeoCheckerSettings {
2933
+ [key: string]: any;
2934
+ }
2935
+
2936
+ export interface SeoCheckerPluginOptions {
2937
+ enabled?: boolean;
2938
+ settings?: SeoCheckerSettings;
2939
+ [key: string]: unknown;
2940
+ }
2941
+
2942
+ export function seoCheckerPlugin(options?: SeoCheckerPluginOptions): WebspressoPlugin;
2943
+
2944
+ export interface AnalyticsPluginOptions {
2945
+ google?: {
2946
+ measurementId?: string;
2947
+ adsId?: string;
2948
+ verificationCode?: string;
2949
+ };
2950
+ gtm?: {
2951
+ containerId?: string;
2952
+ };
2953
+ yandex?: {
2954
+ counterId?: string | number;
2955
+ verificationCode?: string;
2956
+ webvisor?: boolean;
2957
+ clickmap?: boolean;
2958
+ trackLinks?: boolean;
2959
+ accurateTrackBounce?: boolean;
2960
+ };
2961
+ bing?: {
2962
+ uetId?: string;
2963
+ verificationCode?: string;
2964
+ };
2965
+ facebook?: {
2966
+ pixelId?: string;
2967
+ domainVerification?: string;
2968
+ };
2969
+ pinterest?: {
2970
+ verificationCode?: string;
2971
+ };
2972
+ [key: string]: unknown;
2973
+ }
2974
+
2975
+ export function analyticsPlugin(options?: AnalyticsPluginOptions): WebspressoPlugin;
2745
2976
 
2746
2977
  export interface SiteAnalyticsRetentionConfig {
2747
2978
  enabled?: boolean;
@@ -2962,7 +3193,17 @@ export class FileTransport {
2962
3193
  verify(): Promise<boolean>;
2963
3194
  }
2964
3195
 
2965
- export function recaptchaPlugin(options?: Record<string, unknown>): WebspressoPlugin;
3196
+ export interface RecaptchaPluginOptions {
3197
+ siteKey: string;
3198
+ secretKey?: string;
3199
+ version?: 'v2' | 'v3';
3200
+ minScore?: number;
3201
+ expectedAction?: string;
3202
+ defaultV3Action?: string;
3203
+ [key: string]: unknown;
3204
+ }
3205
+
3206
+ export function recaptchaPlugin(options?: RecaptchaPluginOptions): WebspressoPlugin;
2966
3207
 
2967
3208
  export interface SwaggerPluginOptions {
2968
3209
  /** Base path for docs (default: '/_swagger') */
@@ -3005,29 +3246,16 @@ export function swaggerPlugin(options?: SwaggerPluginOptions): WebspressoPlugin;
3005
3246
  export function openapiPlugin(options?: SwaggerPluginOptions): WebspressoPlugin;
3006
3247
  export function apiDocsPlugin(options?: SwaggerPluginOptions): WebspressoPlugin;
3007
3248
 
3008
- export function healthCheckPlugin(options?: Record<string, unknown>): WebspressoPlugin;
3009
-
3010
- export interface CorsPluginOptions {
3011
- origin?:
3012
- | string
3013
- | string[]
3014
- | RegExp
3015
- | ((
3016
- origin: string,
3017
- callback: (err: Error | null, allow?: boolean | string) => void
3018
- ) => void);
3019
- methods?: string | string[];
3020
- allowedHeaders?: string | string[];
3021
- exposedHeaders?: string | string[];
3022
- credentials?: boolean;
3023
- maxAge?: number;
3024
- preflightContinue?: boolean;
3025
- optionsSuccessStatus?: number;
3026
- routes?: string | string[] | boolean;
3027
- global?: boolean;
3249
+ export interface HealthCheckPluginOptions {
3250
+ path?: string;
3251
+ enabled?: boolean;
3252
+ authorize?: (req: any) => boolean;
3253
+ verbose?: boolean;
3254
+ checks?: (context: { req: any; db: any; options: any }) => Promise<Record<string, string>> | Record<string, string>;
3255
+ [key: string]: unknown;
3028
3256
  }
3029
3257
 
3030
- export function corsPlugin(options?: CorsPluginOptions): WebspressoPlugin;
3258
+ export function healthCheckPlugin(options?: HealthCheckPluginOptions): WebspressoPlugin;
3031
3259
 
3032
3260
  export interface RedirectRule {
3033
3261
  from: string | RegExp;
@@ -3437,7 +3665,7 @@ export function webhooksPlugin(options?: WebhooksPluginOptions): WebspressoPlugi
3437
3665
  };
3438
3666
 
3439
3667
  export interface ContentPluginOptions {
3440
- db: import('./index').Database;
3668
+ db: DatabaseInstance;
3441
3669
  adminPath?: string;
3442
3670
  publicApiPath?: string;
3443
3671
  inlineEdit?: boolean;
@@ -3446,7 +3674,7 @@ export interface ContentPluginOptions {
3446
3674
 
3447
3675
  export function contentPlugin(options: ContentPluginOptions): WebspressoPlugin;
3448
3676
 
3449
- export const content: {
3677
+ export declare const content: {
3450
3678
  createContentService: typeof import('./core/content').createContentService;
3451
3679
  parseContentTypeSchema: typeof import('./core/content').parseContentTypeSchema;
3452
3680
  validateEntryData: typeof import('./core/content').validateEntryData;
@@ -3462,6 +3690,7 @@ export interface RestResourcePluginOptions {
3462
3690
  }
3463
3691
 
3464
3692
  export function restResourcePlugin(options?: RestResourcePluginOptions): WebspressoPlugin;
3693
+ export const restResourcesPlugin: typeof restResourcePlugin;
3465
3694
 
3466
3695
  export function ormCacheAdminPlugin(options: { db: DatabaseInstance }): WebspressoPlugin;
3467
3696
 
@@ -3498,6 +3727,8 @@ export interface UploadPluginOptions {
3498
3727
  maxBytes?: number;
3499
3728
  mimeAllowlist?: string[] | null;
3500
3729
  extensionAllowlist?: string[] | null;
3730
+ /** Accept HTML/SVG/JS/XML uploads that are not explicitly allowlisted (default: false) */
3731
+ allowExecutable?: boolean;
3501
3732
  middleware?: RequestHandler | RequestHandler[];
3502
3733
  fieldName?: string;
3503
3734
  multiple?: boolean;
@@ -3827,12 +4058,12 @@ export interface WebspressoKernel {
3827
4058
  createEventBus(): KernelEventBus;
3828
4059
  buildContext: KernelEventBus['buildContext'];
3829
4060
  randomUUID(): string;
3830
- createViewEngine(paths?: { appViews?: string; themeViews?: string }): KernelViewEngine;
4061
+ createViewEngine(paths?: { appViews?: string; themeViews?: string; cache?: boolean }): KernelViewEngine;
3831
4062
  renderTemplate(template: string, data: Record<string, unknown>): string;
3832
4063
  parseQualified(qualified: string): { namespace: string; name: string };
3833
4064
  }
3834
4065
 
3835
- export const kernel: WebspressoKernel;
4066
+ export declare const kernel: WebspressoKernel;
3836
4067
 
3837
4068
  // --- Background Job Queue ---
3838
4069
 
@@ -3883,8 +4114,10 @@ export interface QueueAdapter {
3883
4114
  fail(jobId: string | number, error?: unknown): Promise<Job | null>;
3884
4115
  retry(jobId: string | number, delayMs: number, error?: unknown): Promise<Job | null>;
3885
4116
  getJob(jobId: string | number): Promise<Job | null>;
3886
- getStats(): Promise<{ pending: number; running: number; completed: number; failed: number; total: number }>;
4117
+ getStats(): Promise<{ pending: number; running: number; total: number; completed?: number; failed?: number; delayed?: number }>;
3887
4118
  clear(): Promise<void>;
4119
+ /** Requeue jobs abandoned in 'running' state by a crashed worker; returns the number recovered */
4120
+ recoverStale?(options?: { graceMs?: number; excludeIds?: Array<string | number> }): Promise<number>;
3888
4121
  }
3889
4122
 
3890
4123
  export class MemoryQueueAdapter implements QueueAdapter {
@@ -3972,7 +4205,8 @@ export interface SqsQueueAdapterOptions {
3972
4205
  httpTransport?: unknown;
3973
4206
  }
3974
4207
 
3975
- export class SqsQueueAdapter implements QueueAdapter {
4208
+ /** AWS SQS adapter: no job lookup or clear (SQS has no per-message query) */
4209
+ export class SqsQueueAdapter {
3976
4210
  constructor(options?: SqsQueueAdapterOptions);
3977
4211
  enqueue(job: Job): Promise<Job>;
3978
4212
  dequeue(jobNames?: string[]): Promise<Job | null>;
@@ -3992,7 +4226,8 @@ export interface PubSubQueueAdapterOptions {
3992
4226
  httpTransport?: unknown;
3993
4227
  }
3994
4228
 
3995
- export class PubSubQueueAdapter implements QueueAdapter {
4229
+ /** Push-based Google Pub/Sub adapter: enqueue/dequeue only (no job lookup, stats or clear) */
4230
+ export class PubSubQueueAdapter {
3996
4231
  constructor(options: PubSubQueueAdapterOptions);
3997
4232
  enqueue(job: Job): Promise<Job>;
3998
4233
  dequeue(jobNames?: string[]): Promise<Job | null>;
@@ -4073,7 +4308,7 @@ export class CronExpression {
4073
4308
  export function parseCron(expression: string, options?: { utc?: boolean; timezone?: string; tz?: string }): CronExpression;
4074
4309
  export function isValidCron(expression: string, options?: { utc?: boolean; timezone?: string; tz?: string }): boolean;
4075
4310
  export function resolveCronAlias(str: string): string;
4076
- export const CRON_ALIASES: Record<string, string>;
4311
+ export declare const CRON_ALIASES: Record<string, string>;
4077
4312
 
4078
4313
  export class TaskScheduler {
4079
4314
  queue: QueueManager;
@@ -4110,6 +4345,9 @@ export class QueueManager extends EventEmitter {
4110
4345
  pollInterval?: number;
4111
4346
  jobsDir?: string | null;
4112
4347
  autoStart?: boolean;
4348
+ /** Requeue jobs a crashed worker left 'running' after their timeout plus this grace (default '1m'; false disables) */
4349
+ staleJobGrace?: number | string | false;
4350
+ staleCheckInterval?: number | string;
4113
4351
  retention?: boolean | QueueRetentionConfig;
4114
4352
  retentionDays?: number;
4115
4353
  retentionStatuses?: string[];
@@ -4154,6 +4392,8 @@ export function createQueueManager(options?: {
4154
4392
  pollInterval?: number;
4155
4393
  jobsDir?: string | null;
4156
4394
  autoStart?: boolean;
4395
+ staleJobGrace?: number | string | false;
4396
+ staleCheckInterval?: number | string;
4157
4397
  retention?: boolean | QueueRetentionConfig;
4158
4398
  retentionDays?: number;
4159
4399
  retentionStatuses?: string[];
@@ -4197,24 +4437,39 @@ export function queuePlugin(options?: {
4197
4437
 
4198
4438
  // --- SSR Streaming & Chunked Transfer ---
4199
4439
 
4440
+ export type DeferredSlot =
4441
+ | Promise<unknown>
4442
+ | (() => Promise<unknown> | unknown)
4443
+ | {
4444
+ promise?: Promise<unknown>;
4445
+ fetch?: () => Promise<unknown> | unknown;
4446
+ template?: string;
4447
+ loadingTemplate?: string;
4448
+ errorTemplate?: string;
4449
+ onError?: (err: Error) => void;
4450
+ };
4451
+
4200
4452
  export interface HtmlStreamOptions {
4201
4453
  env: import('nunjucks').Environment;
4202
4454
  templatePath: string;
4203
4455
  context?: Record<string, unknown>;
4204
- defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string; loadingTemplate?: string }>;
4456
+ defer?: Record<string, DeferredSlot>;
4205
4457
  nonce?: string;
4206
4458
  loadingTemplate?: string | null;
4207
4459
  layouts?: CascadingLayoutInfo[];
4460
+ signal?: AbortSignal;
4208
4461
  }
4209
4462
 
4210
4463
  export interface RenderStreamOptions {
4211
4464
  env?: import('nunjucks').Environment;
4212
- defer?: Record<string, Promise<unknown> | { promise: Promise<unknown>; template?: string; loadingTemplate?: string }>;
4465
+ defer?: Record<string, DeferredSlot>;
4213
4466
  status?: number;
4214
4467
  flushImmediately?: boolean;
4215
4468
  nonce?: string;
4216
4469
  loadingTemplate?: string | null;
4217
4470
  layouts?: CascadingLayoutInfo[];
4471
+ signal?: AbortSignal;
4472
+ req?: import('http').IncomingMessage | any;
4218
4473
  }
4219
4474
 
4220
4475
  export function createHtmlStream(options: HtmlStreamOptions): import('stream').Readable;
@@ -4225,7 +4480,7 @@ export function renderStream(
4225
4480
  options?: RenderStreamOptions
4226
4481
  ): Promise<void>;
4227
4482
 
4228
- export const ssr: {
4483
+ export declare const ssr: {
4229
4484
  createHtmlStream: typeof createHtmlStream;
4230
4485
  renderStream: typeof renderStream;
4231
4486
  };
@@ -4309,7 +4564,7 @@ export function createSseStream(
4309
4564
  maybeOptions?: SseOptions
4310
4565
  ): ServerSentEventsStream | Promise<void>;
4311
4566
 
4312
- export const sseStream: {
4567
+ export declare const sseStream: {
4313
4568
  ServerSentEventsStream: typeof ServerSentEventsStream;
4314
4569
  createSseStream: typeof createSseStream;
4315
4570
  formatSseFrame: (data?: any, event?: string, id?: string | number, retry?: number) => string;
@@ -4322,6 +4577,7 @@ export interface TextStreamOptions {
4322
4577
  contentType?: string;
4323
4578
  headers?: Record<string, string>;
4324
4579
  map?: (chunk: any) => any;
4580
+ signal?: AbortSignal;
4325
4581
  }
4326
4582
 
4327
4583
  export class TextStreamController extends EventEmitter {
@@ -4354,7 +4610,7 @@ export function streamJson(
4354
4610
  maybeOptions?: TextStreamOptions
4355
4611
  ): TextStreamController | Promise<void>;
4356
4612
 
4357
- export const stream: {
4613
+ export declare const stream: {
4358
4614
  TextStreamController: typeof TextStreamController;
4359
4615
  streamText: typeof streamText;
4360
4616
  streamJson: typeof streamJson;
@@ -4524,7 +4780,7 @@ export interface XlsxToolkit {
4524
4780
  createServices(options?: Record<string, unknown>): Record<string, unknown>;
4525
4781
  }
4526
4782
 
4527
- export const xlsx: XlsxToolkit;
4783
+ export declare const xlsx: XlsxToolkit;
4528
4784
  export function xlsxPlugin(options?: XlsxPluginOptions): WebspressoPlugin;
4529
4785
 
4530
4786
  // --- CSV Plugin & Toolkit ---
@@ -4594,7 +4850,7 @@ export interface CsvToolkit {
4594
4850
  createServices(options?: Record<string, unknown>): Record<string, unknown>;
4595
4851
  }
4596
4852
 
4597
- export const csv: CsvToolkit;
4853
+ export declare const csv: CsvToolkit;
4598
4854
  export function csvPlugin(options?: CsvPluginOptions): WebspressoPlugin;
4599
4855
 
4600
4856
  // --- Discovery, Pages, API & Modules ---
@@ -4633,13 +4889,72 @@ export function definePage<TData = any, TParams = Record<string, string>, TQuery
4633
4889
  config: DefinePageOptions<TData, TParams, TQuery> | ((ctx: PageContext<TParams, TQuery>) => Promise<TData> | TData)
4634
4890
  ): DefinePageOptions<TData, TParams, TQuery>;
4635
4891
 
4636
- export interface ApiContext<TBody = any, TParams = Record<string, string>, TQuery = Record<string, string>> {
4637
- req: import('express').Request;
4638
- res: import('express').Response;
4892
+ export interface ApiRequest<
4893
+ TBody = any,
4894
+ TParams = Record<string, string>,
4895
+ TQuery = Record<string, string>,
4896
+ THeaders = Record<string, string>
4897
+ > extends Omit<Request, 'params' | 'query' | 'body' | 'session'> {
4898
+ body: TBody;
4899
+ params: TParams;
4900
+ query: TQuery;
4901
+ input: {
4902
+ body: TBody;
4903
+ params: TParams;
4904
+ query: TQuery;
4905
+ headers?: THeaders;
4906
+ };
4907
+ ctx: ApiContext<TBody, TParams, TQuery, THeaders>;
4908
+ service: WebspressoServiceCaller;
4909
+ db?: any;
4910
+ user?: any;
4911
+ auth?: any;
4912
+ session?: any;
4913
+ queue?: any;
4914
+ cache?: any;
4915
+ flags?: any;
4916
+ hasFeature?: (key: string, customContext?: any) => boolean;
4917
+ getVariant?: (key: string, customContext?: any) => string | null;
4918
+ }
4919
+
4920
+ export interface ApiResponse<
4921
+ TBody = any,
4922
+ TParams = Record<string, string>,
4923
+ TQuery = Record<string, string>,
4924
+ THeaders = Record<string, string>
4925
+ > extends Response {
4926
+ input: {
4927
+ body: TBody;
4928
+ params: TParams;
4929
+ query: TQuery;
4930
+ headers?: THeaders;
4931
+ };
4932
+ service: WebspressoServiceCaller;
4933
+ module: string | null;
4934
+ locale?: string;
4935
+ t?: Translator;
4936
+ flags?: any;
4937
+ hasFeature?: (key: string, customContext?: any) => boolean;
4938
+ getVariant?: (key: string, customContext?: any) => string | null;
4939
+ }
4940
+
4941
+ export interface ApiContext<
4942
+ TBody = any,
4943
+ TParams = Record<string, string>,
4944
+ TQuery = Record<string, string>,
4945
+ THeaders = Record<string, string>
4946
+ > {
4947
+ req: ApiRequest<TBody, TParams, TQuery, THeaders>;
4948
+ res: ApiResponse<TBody, TParams, TQuery, THeaders>;
4639
4949
  params: TParams;
4640
4950
  query: TQuery;
4641
4951
  body: TBody;
4642
- input: { body?: TBody; params?: TParams; query?: TQuery; headers?: Record<string, string> };
4952
+ input: {
4953
+ body: TBody;
4954
+ params: TParams;
4955
+ query: TQuery;
4956
+ headers?: THeaders;
4957
+ };
4643
4958
  locale: string;
4644
4959
  t: Translator;
4645
4960
  service: WebspressoServiceCaller;
@@ -4655,25 +4970,157 @@ export interface ApiContext<TBody = any, TParams = Record<string, string>, TQuer
4655
4970
  streamJson?: (sourceOrCallback?: any, maybeOptions?: any) => any;
4656
4971
  }
4657
4972
 
4658
- export interface DefineApiOptions<TResult = any, TBody = any, TParams = Record<string, string>, TQuery = Record<string, string>> {
4973
+ export type ApiSchemaObject = {
4974
+ params?: import('zod').ZodType<any> | unknown;
4975
+ query?: import('zod').ZodType<any> | unknown;
4976
+ body?: import('zod').ZodType<any> | unknown;
4977
+ headers?: import('zod').ZodType<any> | unknown;
4978
+ };
4979
+
4980
+ export type ApiSchemaFunction = (helpers: { z: typeof import('zod').z }) => Record<string, unknown>;
4981
+
4982
+ export type ApiSchemaDefinition = ApiSchemaObject | ApiSchemaFunction;
4983
+
4984
+ type InferSchemaType<T, TFallback = any> = T extends import('zod').ZodTypeAny
4985
+ ? import('zod').z.output<T>
4986
+ : T extends { _output: infer O }
4987
+ ? O
4988
+ : T extends (...args: any[]) => any
4989
+ ? ReturnType<T>
4990
+ : TFallback;
4991
+
4992
+ export type InferApiBody<T, TFallback = any> = T extends { schema: infer S }
4993
+ ? InferApiBodyFromSchema<S, TFallback>
4994
+ : InferApiBodyFromSchema<T, TFallback>;
4995
+
4996
+ export type InferApiBodyFromSchema<S, TFallback = any> = S extends (helpers: any) => { body: infer B }
4997
+ ? InferSchemaType<B, TFallback>
4998
+ : S extends { body: infer B }
4999
+ ? InferSchemaType<B, TFallback>
5000
+ : TFallback;
5001
+
5002
+ export type InferApiParams<T, TFallback = Record<string, string>> = T extends { schema: infer S }
5003
+ ? InferApiParamsFromSchema<S, TFallback>
5004
+ : InferApiParamsFromSchema<T, TFallback>;
5005
+
5006
+ export type InferApiParamsFromSchema<S, TFallback = Record<string, string>> = S extends (helpers: any) => { params: infer P }
5007
+ ? InferSchemaType<P, TFallback>
5008
+ : S extends { params: infer P }
5009
+ ? InferSchemaType<P, TFallback>
5010
+ : TFallback;
5011
+
5012
+ export type InferApiQuery<T, TFallback = Record<string, string>> = T extends { schema: infer S }
5013
+ ? InferApiQueryFromSchema<S, TFallback>
5014
+ : InferApiQueryFromSchema<T, TFallback>;
5015
+
5016
+ export type InferApiQueryFromSchema<S, TFallback = Record<string, string>> = S extends (helpers: any) => { query: infer Q }
5017
+ ? InferSchemaType<Q, TFallback>
5018
+ : S extends { query: infer Q }
5019
+ ? InferSchemaType<Q, TFallback>
5020
+ : TFallback;
5021
+
5022
+ export type InferApiHeaders<T, TFallback = Record<string, string>> = T extends { schema: infer S }
5023
+ ? InferApiHeadersFromSchema<S, TFallback>
5024
+ : InferApiHeadersFromSchema<T, TFallback>;
5025
+
5026
+ export type InferApiHeadersFromSchema<S, TFallback = Record<string, string>> = S extends (helpers: any) => { headers: infer H }
5027
+ ? InferSchemaType<H, TFallback>
5028
+ : S extends { headers: infer H }
5029
+ ? InferSchemaType<H, TFallback>
5030
+ : TFallback;
5031
+
5032
+ export type InferApiOutput<T> = T extends DefineApiOptions<infer TResult, any, any, any, any, any>
5033
+ ? TResult
5034
+ : T extends { handler: (...args: any[]) => Promise<infer TResult> }
5035
+ ? TResult
5036
+ : T extends { handler: (...args: any[]) => infer TResult }
5037
+ ? TResult
5038
+ : T extends (...args: any[]) => Promise<infer TResult>
5039
+ ? TResult
5040
+ : T extends (...args: any[]) => infer TResult
5041
+ ? TResult
5042
+ : any;
5043
+
5044
+ export type InferApiInput<T> = {
5045
+ body: InferApiBody<T>;
5046
+ params: InferApiParams<T>;
5047
+ query: InferApiQuery<T>;
5048
+ headers?: InferApiHeaders<T>;
5049
+ };
5050
+
5051
+ type ApiNoInfer<T> = [T][T extends any ? 0 : never];
5052
+
5053
+ export interface DefineApiOptions<
5054
+ TResult = any,
5055
+ TBody = any,
5056
+ TParams = Record<string, string>,
5057
+ TQuery = Record<string, string>,
5058
+ THeaders = Record<string, string>,
5059
+ TSchema = unknown
5060
+ > {
4659
5061
  description?: string;
4660
5062
  tags?: string[];
4661
5063
  middleware?: (string | import('express').RequestHandler | [string, Record<string, unknown>])[];
4662
5064
  flag?: string | { key: string; statusCode?: number; message?: string };
4663
- schema?: {
4664
- params?: unknown;
4665
- query?: unknown;
4666
- body?: unknown;
4667
- headers?: unknown;
4668
- } | ((helpers: { z: typeof import('zod').z }) => Record<string, unknown>);
5065
+ schema?: TSchema;
4669
5066
  response?: Record<number | string, unknown>;
4670
- handler: (req: import('express').Request, ctx: ApiContext<TBody, TParams, TQuery>) => Promise<TResult> | TResult;
5067
+ handler: (
5068
+ req: ApiRequest<TBody, TParams, TQuery, THeaders>,
5069
+ res: ApiResponse<TBody, TParams, TQuery, THeaders>,
5070
+ ctx: ApiContext<TBody, TParams, TQuery, THeaders>
5071
+ ) => Promise<TResult> | TResult;
4671
5072
  [key: string]: unknown;
4672
5073
  }
4673
5074
 
4674
- export function defineApi<TResult = any, TBody = any, TParams = Record<string, string>, TQuery = Record<string, string>>(
4675
- config: DefineApiOptions<TResult, TBody, TParams, TQuery> | ((req: import('express').Request, ctx: ApiContext<TBody, TParams, TQuery>) => Promise<TResult> | TResult)
4676
- ): DefineApiOptions<TResult, TBody, TParams, TQuery>;
5075
+ export function defineApi<
5076
+ TSchema extends ApiSchemaDefinition,
5077
+ TResult = any,
5078
+ TBody = InferApiBodyFromSchema<TSchema>,
5079
+ TParams = InferApiParamsFromSchema<TSchema>,
5080
+ TQuery = InferApiQueryFromSchema<TSchema>,
5081
+ THeaders = InferApiHeadersFromSchema<TSchema>
5082
+ >(
5083
+ config: {
5084
+ schema: TSchema;
5085
+ description?: string;
5086
+ tags?: string[];
5087
+ middleware?: (string | import('express').RequestHandler | [string, Record<string, unknown>])[];
5088
+ flag?: string | { key: string; statusCode?: number; message?: string };
5089
+ response?: Record<number | string, unknown>;
5090
+ handler: (
5091
+ req: ApiRequest<ApiNoInfer<TBody>, ApiNoInfer<TParams>, ApiNoInfer<TQuery>, ApiNoInfer<THeaders>>,
5092
+ res: ApiResponse<ApiNoInfer<TBody>, ApiNoInfer<TParams>, ApiNoInfer<TQuery>, ApiNoInfer<THeaders>>,
5093
+ ctx: ApiContext<ApiNoInfer<TBody>, ApiNoInfer<TParams>, ApiNoInfer<TQuery>, ApiNoInfer<THeaders>>
5094
+ ) => Promise<TResult> | TResult;
5095
+ [key: string]: unknown;
5096
+ }
5097
+ ): DefineApiOptions<TResult, TBody, TParams, TQuery, THeaders, TSchema>;
5098
+
5099
+ export function defineApi<
5100
+ TResult = any,
5101
+ TBody = any,
5102
+ TParams = Record<string, string>,
5103
+ TQuery = Record<string, string>,
5104
+ THeaders = Record<string, string>
5105
+ >(
5106
+ config: DefineApiOptions<TResult, TBody, TParams, TQuery, THeaders>
5107
+ ): DefineApiOptions<TResult, TBody, TParams, TQuery, THeaders>;
5108
+
5109
+ export function defineApi<
5110
+ TResult = any,
5111
+ TBody = any,
5112
+ TParams = Record<string, string>,
5113
+ TQuery = Record<string, string>,
5114
+ THeaders = Record<string, string>
5115
+ >(
5116
+ handler: (
5117
+ req: ApiRequest<TBody, TParams, TQuery, THeaders>,
5118
+ res: ApiResponse<TBody, TParams, TQuery, THeaders>,
5119
+ ctx: ApiContext<TBody, TParams, TQuery, THeaders>
5120
+ ) => Promise<TResult> | TResult
5121
+ ): DefineApiOptions<TResult, TBody, TParams, TQuery, THeaders>;
5122
+
5123
+ export declare const api: typeof defineApi;
4677
5124
 
4678
5125
  export interface DefineModuleOptions {
4679
5126
  name: string;
@@ -4965,6 +5412,8 @@ export interface OAuthPluginOptions {
4965
5412
  pkce?: boolean;
4966
5413
  stateTtlMs?: number;
4967
5414
  defaultReturnTo?: string;
5415
+ /** Absolute origins `returnTo` may redirect to; same-site paths are always allowed */
5416
+ allowedRedirectOrigins?: string[];
4968
5417
  failureRedirect?: string;
4969
5418
  findOrCreateUser?: (params: {
4970
5419
  provider: string;
@@ -5355,9 +5804,119 @@ export interface RlsPluginOptions {
5355
5804
  enabled?: boolean;
5356
5805
  }
5357
5806
 
5358
- export function rlsPlugin(options?: RlsPluginOptions): import('./src/plugin-manager').Plugin;
5807
+ export function rlsPlugin(options?: RlsPluginOptions): import('./core/plugins').Plugin;
5359
5808
  export function createRlsMiddleware(options?: RlsPluginOptions): (req: any, res: any, next: (err?: any) => void) => void;
5360
5809
 
5810
+ // --- Security Shield Plugin ---
5811
+ export interface SecurityPluginOptions {
5812
+ headers?: boolean | {
5813
+ csp?: boolean | Record<string, string[] | boolean | string>;
5814
+ cspReportOnly?: boolean;
5815
+ hsts?: boolean | { maxAge?: number; includeSubDomains?: boolean; preload?: boolean; force?: boolean };
5816
+ frameGuard?: 'SAMEORIGIN' | 'DENY' | string | boolean;
5817
+ noSniff?: boolean;
5818
+ referrerPolicy?: string | boolean;
5819
+ permissionsPolicy?: string | boolean;
5820
+ xssFilter?: boolean;
5821
+ dnsPrefetchControl?: boolean;
5822
+ crossOriginOpenerPolicy?: string | boolean;
5823
+ crossOriginResourcePolicy?: string | boolean;
5824
+ hidePoweredBy?: boolean;
5825
+ generateNonce?: boolean;
5826
+ };
5827
+ firewall?: boolean | {
5828
+ whitelist?: string[];
5829
+ blacklist?: string[];
5830
+ autoBan?: {
5831
+ enabled?: boolean;
5832
+ threshold?: number;
5833
+ window?: string | number;
5834
+ duration?: string | number;
5835
+ };
5836
+ };
5837
+ honeypot?: boolean | {
5838
+ honeypots?: boolean | string[];
5839
+ detectTraversal?: boolean;
5840
+ blockBadBots?: boolean;
5841
+ instantBan?: boolean;
5842
+ violationWeight?: number;
5843
+ honeypotStatus?: number;
5844
+ };
5845
+ bruteForce?: boolean | {
5846
+ routes?: string[];
5847
+ maxAttempts?: number;
5848
+ window?: string | number;
5849
+ lockout?: string | number;
5850
+ progressiveDelay?: boolean;
5851
+ banOnExceeded?: boolean;
5852
+ };
5853
+ incidents?: boolean | {
5854
+ maxSize?: number;
5855
+ };
5856
+ adminPanel?: boolean;
5857
+ adminTitle?: string;
5858
+ adminApiPrefix?: string;
5859
+ menuOrder?: number;
5860
+ }
5861
+
5862
+ export function securityPlugin(options?: SecurityPluginOptions): import('./core/plugins').Plugin & {
5863
+ api?: {
5864
+ getFirewall(): any;
5865
+ getIncidentRecorder(): any;
5866
+ isBanned(ip: string): { banned: boolean; reason?: string; expiresAt?: number };
5867
+ ban(ip: string, options?: { reason?: string; duration?: string | number; meta?: Record<string, any> }): any;
5868
+ unban(ip: string): boolean;
5869
+ listBanned(options?: { page?: number; limit?: number; search?: string; reason?: string }): any;
5870
+ getStats(): any;
5871
+ audit(app?: any): any;
5872
+ };
5873
+ };
5874
+ export function createSecurityHeadersMiddleware(options?: any): RequestHandler;
5875
+ export function createFirewallMiddleware(firewall: any): RequestHandler;
5876
+
5877
+ export class FirewallManager {
5878
+ constructor(options?: any);
5879
+ isBanned(ip: string): { banned: boolean; reason?: string; expiresAt?: number; isPermanent?: boolean; remainingMs?: number };
5880
+ isWhitelisted(ip: string): boolean;
5881
+ ban(ip: string, options?: { reason?: string; duration?: string | number; meta?: Record<string, any> }): any;
5882
+ unban(ip: string): boolean;
5883
+ recordViolation(ip: string, violation?: { type?: string; weight?: number; path?: string; userAgent?: string }): { banned: boolean; count: number; autoBanned: boolean };
5884
+ listBanned(filter?: { page?: number; limit?: number; search?: string; reason?: string }): { items: any[]; total: number; page: number; limit: number; totalPages: number };
5885
+ getStats(): { activeBans: number; permanentBans: number; autoBans24h: number; totalBans: number; totalViolations: number; whitelistCount: number; blacklistCount: number };
5886
+ }
5887
+
5888
+ export class IncidentRecorder {
5889
+ constructor(options?: { maxSize?: number });
5890
+ record(data: {
5891
+ type: string;
5892
+ ip: string;
5893
+ method?: string;
5894
+ path?: string;
5895
+ userAgent?: string;
5896
+ reason?: string;
5897
+ actionTaken?: 'blocked' | 'banned' | 'throttled' | 'warned' | string;
5898
+ details?: Record<string, any>;
5899
+ }): any;
5900
+ list(filter?: { limit?: number; type?: string; search?: string }): { items: any[]; total: number };
5901
+ clear(): void;
5902
+ getStats(): { last24hCount: number; breakdown: Record<string, number> };
5903
+ }
5904
+
5905
+ export function auditSecurityPosture(context?: {
5906
+ options?: any;
5907
+ firewall?: any;
5908
+ incidentRecorder?: any;
5909
+ app?: any;
5910
+ }): {
5911
+ score: number;
5912
+ grade: string;
5913
+ checks: Array<{ id: string; category: string; title: string; description: string; passed: boolean; weight: number; recommendation: string | null }>;
5914
+ totalChecks: number;
5915
+ passedChecks: number;
5916
+ failedChecks: number;
5917
+ auditedAt: string;
5918
+ };
5919
+
5361
5920
  // --- Structured Cloud Logging ---
5362
5921
  export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
5363
5922
  export type LogFormat = 'auto' | 'gcp' | 'aws' | 'json' | 'pretty';
@@ -5577,7 +6136,577 @@ export namespace repl {
5577
6136
  };
5578
6137
  }
5579
6138
 
6139
+ // --- Ambient Request & Execution Context (AsyncLocalStorage) ---
6140
+ export interface RequestContextStore {
6141
+ req?: any;
6142
+ res?: any;
6143
+ db?: DatabaseInstance | any;
6144
+ user?: any;
6145
+ auth?: any;
6146
+ session?: any;
6147
+ logger?: any;
6148
+ service?: (name: string, input?: any, opts?: any) => Promise<any>;
6149
+ queue?: any;
6150
+ cache?: any;
6151
+ [key: string]: any;
6152
+ }
6153
+
6154
+ export function runWithContext<T>(context: RequestContextStore, fn: () => T): T;
6155
+ export function withContext<T>(overrides: Partial<RequestContextStore>, fn: () => T): T;
6156
+ export function getContext(): RequestContextStore | null;
6157
+ export function useContext<T = RequestContextStore>(): T;
6158
+ export function useDb<T = DatabaseInstance>(): T | null;
6159
+ export function useAuth<T = any>(): T | null;
6160
+ export function useUser<T = any>(): T | null;
6161
+ export function useLogger(): any;
6162
+ export function useReq<T = any>(): T | null;
6163
+ export function useRes<T = any>(): T | null;
6164
+ export function useParams<T = Record<string, string>>(): T;
6165
+ export function useQuery<T = Record<string, any>>(): T;
6166
+ export function useService<T = any>(name: string, input?: any, opts?: any): Promise<T>;
6167
+ export function useQueue(): any;
6168
+ export function useCache(): any;
6169
+ export function useBreaker(name: string, options?: any): any;
6170
+ export function useTransaction<T = any>(callback: (trx: any) => Promise<T>): Promise<T>;
6171
+
6172
+
6173
+
6174
+
6175
+
6176
+
6177
+
6178
+ // --- Runtime exports that previously had no declarations ---------------------------------
6179
+
6180
+ /** Aliases of definePage / defineModule */
6181
+ export declare const page: typeof definePage;
6182
+ export declare const module: typeof defineModule;
6183
+
6184
+ /** Circuit breaker state constants */
6185
+ export declare const STATE_CLOSED: 'CLOSED';
6186
+ export declare const STATE_OPEN: 'OPEN';
6187
+ export declare const STATE_HALF_OPEN: 'HALF_OPEN';
6188
+
6189
+ /** Health probe helpers (core/health) */
6190
+ export function probeDatabase(db: unknown): Promise<{ status: 'up' | 'down' | 'skipped'; latencyMs?: number; error?: string; message?: string }>;
6191
+ export function probeQueue(queue: unknown): Promise<{ status: 'up' | 'down' | 'skipped'; stats?: Record<string, unknown>; error?: string; message?: string }>;
6192
+ export function probeCustomChecks(
6193
+ checks?: Record<string, (context: unknown) => Promise<unknown> | unknown>,
6194
+ context?: unknown,
6195
+ timeoutMs?: number
6196
+ ): Promise<Record<string, { status: 'up' | 'down'; error?: string; [key: string]: unknown }>>;
6197
+ export function formatMb(bytes: number): string;
6198
+ export function createEventLoopMonitor(options?: { resolution?: number }): {
6199
+ start(): void;
6200
+ stop(): void;
6201
+ getStats(): { meanMs: number; maxMs: number; p50Ms: number; p99Ms: number };
6202
+ };
6203
+ export function getSystemMetrics(monitor?: unknown): Record<string, unknown>;
6204
+
6205
+ /** ORM cache configuration normalizer */
6206
+ export function normalizeCacheConfig(config: unknown): Record<string, unknown>;
6207
+
6208
+ /** Route mounting (advanced) */
6209
+ export function mountDiscoveredRoutes(
6210
+ app: import('express').Application,
6211
+ routeTable: unknown,
6212
+ options?: Record<string, unknown>
6213
+ ): { routeMetadata: Array<Record<string, unknown>>; registerDynamicDiscoveredRoutes: () => void };
6214
+
6215
+ /** ORM repository factory and relation loaders (advanced) */
6216
+ export function createRepository<T = Record<string, any>>(
6217
+ model: ModelDefinition<T>,
6218
+ knex: import('knex').Knex | import('knex').Knex.Transaction,
6219
+ scopeContext?: ScopeContext,
6220
+ cacheLayer?: unknown
6221
+ ): Repository<T>;
6222
+ export function loadRelations(
6223
+ records: Record<string, any>[],
6224
+ model: ModelDefinition<any>,
6225
+ relations: string[] | Record<string, unknown>,
6226
+ knex: import('knex').Knex,
6227
+ options?: Record<string, unknown>
6228
+ ): Promise<Record<string, any>[]>;
6229
+ export function loadRelation(
6230
+ records: Record<string, any>[],
6231
+ model: ModelDefinition<any>,
6232
+ relationName: string,
6233
+ knex: import('knex').Knex,
6234
+ options?: Record<string, unknown>
6235
+ ): Promise<Record<string, any>[]>;
6236
+ export function parseRelationTree(includes: string | string[]): Record<string, unknown>;
6237
+
6238
+ /** Kernel repository base class (core/kernel) */
6239
+ export declare const BaseRepository: KernelBaseRepositoryConstructor;
6240
+
6241
+ /** Static export helpers (core/export) */
6242
+ export function urlToFilePath(url: string, outDir?: string): string;
6243
+ export function generateSitemapXml(urls: Array<string | { loc: string; lastmod?: string | Date; changefreq?: string; priority?: number }>, options?: { baseUrl?: string }): string;
6244
+ export function copyDirRecursive(src: string, dest: string): void;
6245
+
6246
+ /** Native dual auth (core/auth) */
6247
+ export function createAuth(config: Record<string, unknown>): any;
6248
+ export function quickAuth(options: Record<string, unknown>): any;
6249
+ export function createAuthMiddleware(authManager: unknown, options?: Record<string, unknown>): import('express').RequestHandler;
6250
+ export function setupAuthMiddleware(app: import('express').Application, authManager: unknown, options?: Record<string, unknown>): void;
6251
+
6252
+ /** Dev tooling */
6253
+ export function createDevReloadHub(options?: Record<string, unknown>): {
6254
+ broadcast(event: string, data?: unknown): void;
6255
+ close(): void;
6256
+ [key: string]: unknown;
6257
+ };
6258
+ export function createWebspressoClient(options?: { baseUrl?: string; fetch?: typeof fetch; headers?: Record<string, string> }): any;
6259
+ export class WebspressoClientError extends Error {
6260
+ status?: number;
6261
+ body?: unknown;
6262
+ }
6263
+ export function buildSwaggerUiHtml(options?: { specUrl?: string; title?: string; [key: string]: unknown }): string;
6264
+ export function buildScalarUiHtml(options?: { specUrl?: string; title?: string; [key: string]: unknown }): string;
6265
+
6266
+ /** Plugin helpers re-exported from webspresso/plugins */
6267
+ export function createBasicAuthMiddleware(options?: BasicAuthPluginOptions): import('express').RequestHandler;
6268
+ export function polarPlugin(options?: Record<string, unknown>): WebspressoPlugin;
6269
+ export class WebhookDispatcher {
6270
+ constructor(options?: Record<string, unknown>);
6271
+ dispatch(event: string, payload?: unknown, options?: Record<string, unknown>): Promise<unknown>;
6272
+ [key: string]: any;
6273
+ }
6274
+
6275
+ /** Namespaced module objects (each also exposes the typed top-level exports above) */
6276
+ export declare const context: Record<string, any>;
6277
+ export declare const appContext: Record<string, any>;
6278
+ export declare const requestContext: Record<string, any>;
6279
+ export declare const requestContextStorage: import('async_hooks').AsyncLocalStorage<any>;
6280
+ export declare const services: {
6281
+ ServiceRegistry: typeof ServiceRegistry;
6282
+ createServiceRegistry: typeof createServiceRegistry;
6283
+ defineService: typeof defineService;
6284
+ [key: string]: any;
6285
+ };
6286
+ export declare const errors: {
6287
+ WebspressoError: typeof WebspressoError;
6288
+ HttpError: typeof HttpError;
6289
+ normalizeError: typeof normalizeError;
6290
+ [key: string]: any;
6291
+ };
6292
+ export declare const orm: {
6293
+ createDatabase: typeof createDatabase;
6294
+ createRepository: typeof createRepository;
6295
+ [key: string]: any;
6296
+ };
6297
+ export declare const studio: Record<string, any>;
6298
+ export declare const auth: {
6299
+ createAuth: typeof createAuth;
6300
+ quickAuth: typeof quickAuth;
6301
+ [key: string]: any;
6302
+ };
6303
+ export declare const validation: {
6304
+ z: typeof z;
6305
+ [key: string]: any;
6306
+ };
6307
+ export declare const queue: {
6308
+ Job: typeof Job;
6309
+ QueueManager: typeof QueueManager;
6310
+ createQueueManager: typeof createQueueManager;
6311
+ [key: string]: any;
6312
+ };
6313
+ export declare const dev: Record<string, any>;
6314
+ export declare const typegen: Record<string, any>;
6315
+ export declare const webhooks: typeof webhooksPlugin & Record<string, any>;
6316
+ export declare const mail: {
6317
+ Mailer: typeof Mailer;
6318
+ createMailer: typeof createMailer;
6319
+ [key: string]: any;
6320
+ };
6321
+ export declare const logger: {
6322
+ CloudLogger: typeof CloudLogger;
6323
+ createLogger: typeof createLogger;
6324
+ [key: string]: any;
6325
+ };
6326
+ export declare const flags: {
6327
+ FeatureFlagManager: typeof FeatureFlagManager;
6328
+ createFeatureFlagManager: typeof createFeatureFlagManager;
6329
+ [key: string]: any;
6330
+ };
5580
6331
 
6332
+ /* ============================================================================
6333
+ * Datastar Client Behavior Layer & SSR Fragments (core/client)
6334
+ * ========================================================================= */
6335
+
6336
+ export type ClientConcurrencyPolicy = 'latest' | 'drop' | 'queue' | 'parallel';
6337
+ export type ClientRequestErrorKind = 'http' | 'network' | 'validation' | 'canceled';
6338
+
6339
+ export class ClientRequestError<TData = unknown> extends Error {
6340
+ readonly kind: ClientRequestErrorKind;
6341
+ readonly status: number;
6342
+ readonly data: TData | null;
6343
+ readonly fieldErrors: Record<string, string>;
6344
+ readonly formError: string;
6345
+ readonly method: string;
6346
+ readonly url: string;
6347
+ readonly isCanceled: boolean;
6348
+ readonly isValidation: boolean;
6349
+ readonly isNetwork: boolean;
6350
+ readonly isHttp: boolean;
6351
+ constructor(options: {
6352
+ message: string;
6353
+ kind: ClientRequestErrorKind;
6354
+ status?: number;
6355
+ data?: TData | null;
6356
+ fieldErrors?: Record<string, string>;
6357
+ formError?: string;
6358
+ method?: string;
6359
+ url?: string;
6360
+ cause?: unknown;
6361
+ });
6362
+ }
5581
6363
 
6364
+ export interface ClientRequestCallOptions<
6365
+ TQuery = Record<string, unknown>,
6366
+ TParams = Record<string, string | number>
6367
+ > {
6368
+ query?: TQuery;
6369
+ params?: TParams;
6370
+ headers?: Record<string, string>;
6371
+ signal?: AbortSignal;
6372
+ key?: string;
6373
+ concurrency?: ClientConcurrencyPolicy;
6374
+ formData?: boolean;
6375
+ skipInvalidation?: boolean;
6376
+ }
6377
+
6378
+ export interface AppApiRouteMap {
6379
+ GET: Record<string, { input: any; response: any }>;
6380
+ POST: Record<string, { input: any; response: any }>;
6381
+ PUT: Record<string, { input: any; response: any }>;
6382
+ PATCH: Record<string, { input: any; response: any }>;
6383
+ DELETE: Record<string, { input: any; response: any }>;
6384
+ }
6385
+
6386
+ export interface ClientTask<TData = any, TArgs extends unknown[] = any[]> {
6387
+ readonly pending: boolean;
6388
+ readonly data: TData | null;
6389
+ readonly error: ClientRequestError | Error | null;
6390
+ readonly stale: boolean;
6391
+ run(...args: TArgs): Promise<TData | undefined>;
6392
+ cancel(): void;
6393
+ dispose(): void;
6394
+ }
5582
6395
 
6396
+ export interface ClientTaskOptions {
6397
+ concurrency?: ClientConcurrencyPolicy;
6398
+ policy?: ClientConcurrencyPolicy;
6399
+ key?: string;
6400
+ }
5583
6401
 
6402
+ export interface ClientFormFillOptions {
6403
+ baseline?: boolean;
6404
+ }
6405
+
6406
+ export interface ClientApiClient {
6407
+ get<
6408
+ P extends string,
6409
+ TResponse = P extends keyof AppApiRouteMap['GET'] ? AppApiRouteMap['GET'][P]['response'] : unknown,
6410
+ TQuery = P extends keyof AppApiRouteMap['GET'] ? AppApiRouteMap['GET'][P]['input']['query'] : Record<string, unknown>,
6411
+ TParams = P extends keyof AppApiRouteMap['GET'] ? AppApiRouteMap['GET'][P]['input']['params'] : Record<string, string | number>
6412
+ >(
6413
+ url: P,
6414
+ options?: ClientRequestCallOptions<TQuery, TParams>
6415
+ ): Promise<TResponse>;
6416
+
6417
+ post<
6418
+ P extends string,
6419
+ TResponse = P extends keyof AppApiRouteMap['POST'] ? AppApiRouteMap['POST'][P]['response'] : unknown,
6420
+ TBody = P extends keyof AppApiRouteMap['POST'] ? AppApiRouteMap['POST'][P]['input']['body'] : unknown,
6421
+ TQuery = P extends keyof AppApiRouteMap['POST'] ? AppApiRouteMap['POST'][P]['input']['query'] : Record<string, unknown>,
6422
+ TParams = P extends keyof AppApiRouteMap['POST'] ? AppApiRouteMap['POST'][P]['input']['params'] : Record<string, string | number>
6423
+ >(
6424
+ url: P,
6425
+ body?: TBody,
6426
+ options?: ClientRequestCallOptions<TQuery, TParams>
6427
+ ): Promise<TResponse>;
6428
+
6429
+ put<
6430
+ P extends string,
6431
+ TResponse = P extends keyof AppApiRouteMap['PUT'] ? AppApiRouteMap['PUT'][P]['response'] : unknown,
6432
+ TBody = P extends keyof AppApiRouteMap['PUT'] ? AppApiRouteMap['PUT'][P]['input']['body'] : unknown,
6433
+ TQuery = P extends keyof AppApiRouteMap['PUT'] ? AppApiRouteMap['PUT'][P]['input']['query'] : Record<string, unknown>,
6434
+ TParams = P extends keyof AppApiRouteMap['PUT'] ? AppApiRouteMap['PUT'][P]['input']['params'] : Record<string, string | number>
6435
+ >(
6436
+ url: P,
6437
+ body?: TBody,
6438
+ options?: ClientRequestCallOptions<TQuery, TParams>
6439
+ ): Promise<TResponse>;
6440
+
6441
+ patch<
6442
+ P extends string,
6443
+ TResponse = P extends keyof AppApiRouteMap['PATCH'] ? AppApiRouteMap['PATCH'][P]['response'] : unknown,
6444
+ TBody = P extends keyof AppApiRouteMap['PATCH'] ? AppApiRouteMap['PATCH'][P]['input']['body'] : unknown,
6445
+ TQuery = P extends keyof AppApiRouteMap['PATCH'] ? AppApiRouteMap['PATCH'][P]['input']['query'] : Record<string, unknown>,
6446
+ TParams = P extends keyof AppApiRouteMap['PATCH'] ? AppApiRouteMap['PATCH'][P]['input']['params'] : Record<string, string | number>
6447
+ >(
6448
+ url: P,
6449
+ body?: TBody,
6450
+ options?: ClientRequestCallOptions<TQuery, TParams>
6451
+ ): Promise<TResponse>;
6452
+
6453
+ delete<
6454
+ P extends string,
6455
+ TResponse = P extends keyof AppApiRouteMap['DELETE'] ? AppApiRouteMap['DELETE'][P]['response'] : unknown,
6456
+ TBody = P extends keyof AppApiRouteMap['DELETE'] ? AppApiRouteMap['DELETE'][P]['input']['body'] : unknown,
6457
+ TQuery = P extends keyof AppApiRouteMap['DELETE'] ? AppApiRouteMap['DELETE'][P]['input']['query'] : Record<string, unknown>,
6458
+ TParams = P extends keyof AppApiRouteMap['DELETE'] ? AppApiRouteMap['DELETE'][P]['input']['params'] : Record<string, string | number>
6459
+ >(
6460
+ url: P,
6461
+ body?: TBody,
6462
+ options?: ClientRequestCallOptions<TQuery, TParams>
6463
+ ): Promise<TResponse>;
6464
+
6465
+ raw(url: string, options?: RequestInit & ClientRequestCallOptions): Promise<Response>;
6466
+ stream(url: string, options?: ClientRequestCallOptions): Promise<ReadableStream<Uint8Array> | Response>;
6467
+ abortKey(key: string): void;
6468
+ abortAll(): void;
6469
+ }
6470
+
6471
+ export interface ClientFormSubmitResult<TData = any> {
6472
+ ok: boolean;
6473
+ data?: TData;
6474
+ refreshOk?: boolean;
6475
+ refreshError?: Error | null;
6476
+ error?: ClientRequestError | Error;
6477
+ aborted?: boolean;
6478
+ }
6479
+
6480
+ export interface ClientFormHandle<
6481
+ TValues extends Record<string, any> = Record<string, any>,
6482
+ TResponse = any
6483
+ > {
6484
+ readonly name: string;
6485
+ readonly el: HTMLFormElement | null;
6486
+ readonly pending: boolean;
6487
+ readonly dirty: boolean;
6488
+ readonly errors: Record<string, string>;
6489
+ readonly formError: string;
6490
+ readonly fieldErrors: Partial<Record<keyof TValues & string, string>> & Record<string, string>;
6491
+ disabled: boolean;
6492
+ values(): TValues;
6493
+ read(submitter?: HTMLElement | null): TValues;
6494
+ fill(values: Partial<TValues> & Record<string, unknown>, options?: ClientFormFillOptions): this;
6495
+ setAction(url: string): this;
6496
+ setRouteParams(params: Record<string, string | number>): this;
6497
+ setDisabled(disabled: boolean): this;
6498
+ reset(): void;
6499
+ clear(): void;
6500
+ setErrors(fieldErrors?: Partial<Record<keyof TValues & string, string>>, formError?: string): void;
6501
+ clearErrors(): void;
6502
+ submit(submitter?: HTMLElement | null): Promise<ClientFormSubmitResult<TResponse>>;
6503
+ onSuccess(callback: (data: TResponse, meta: { refreshOk: boolean; refreshError: Error | null }) => void): () => void;
6504
+ destroy(): void;
6505
+ }
6506
+
6507
+ export interface ControllerFormsRegistry {
6508
+ get<TValues extends Record<string, any> = Record<string, any>, TResponse = any>(
6509
+ formNameOrElement: string | HTMLFormElement,
6510
+ options?: {
6511
+ resetOnSuccess?: boolean;
6512
+ clearOnSuccess?: boolean;
6513
+ redirectOnSuccess?: string | ((data: TResponse) => string | void);
6514
+ onSuccess?: (data: TResponse, meta: { refreshOk: boolean; refreshError: Error | null }) => void;
6515
+ }
6516
+ ): ClientFormHandle<TValues, TResponse>;
6517
+ all(): ClientFormHandle[];
6518
+ }
6519
+
6520
+ export interface ControllerFragmentHandle<TInput extends Record<string, any> = Record<string, any>> {
6521
+ readonly input: TInput;
6522
+ refresh(
6523
+ nextInput?: Partial<TInput> & Record<string, unknown>,
6524
+ options?: { replaceInput?: boolean }
6525
+ ): Promise<{ ok?: boolean; refreshed: string[]; errors?: Error[]; skipped?: boolean; canceled?: boolean }>;
6526
+ }
6527
+
6528
+ export interface ControllerContext<
6529
+ TState extends Record<string, any> = Record<string, any>,
6530
+ TTasks extends Record<string, ClientTask> = Record<string, ClientTask>
6531
+ > {
6532
+ readonly el: HTMLElement;
6533
+ readonly instanceId: string;
6534
+ readonly name: string;
6535
+ readonly state: TState;
6536
+ readonly api: ClientApiClient;
6537
+ readonly forms: ControllerFormsRegistry;
6538
+ readonly tasks: TTasks;
6539
+ readonly signal: AbortSignal;
6540
+ readonly isConnected: () => boolean;
6541
+ readonly isDisposed: () => boolean;
6542
+ task<TData = any, TArgs extends unknown[] = any[]>(
6543
+ runFn: (...args: TArgs) => Promise<TData>,
6544
+ options?: ClientTaskOptions
6545
+ ): ClientTask<TData, TArgs>;
6546
+ param(name: string, actionEl?: HTMLElement): string | null;
6547
+ target<T extends Element = HTMLElement>(targetName: string): T | null;
6548
+ targets<T extends Element = HTMLElement>(targetName: string): T[];
6549
+ on(
6550
+ targetOrEvent: EventTarget | string,
6551
+ eventOrHandler: string | ((event: Event) => void),
6552
+ maybeHandlerOrOptions?: ((event: Event) => void) | AddEventListenerOptions,
6553
+ maybeOptions?: AddEventListenerOptions
6554
+ ): () => void;
6555
+ emit<TDetail = unknown>(eventName: string, detail?: TDetail, options?: CustomEventInit<TDetail>): boolean;
6556
+ effect(fn: () => void | (() => void)): () => void;
6557
+ interval(fn: () => void, ms: number): () => void;
6558
+ timeout(fn: () => void, ms: number): () => void;
6559
+ invalidate(tags: string | string[]): Promise<{ ok?: boolean; refreshed: string[]; errors?: Error[]; skipped?: boolean }>;
6560
+ refresh<TInput extends Record<string, any> = Record<string, any>>(
6561
+ idOrName: string,
6562
+ nextInput?: Partial<TInput> & Record<string, unknown>,
6563
+ options?: { replaceInput?: boolean }
6564
+ ): Promise<{ ok?: boolean; refreshed: string[]; errors?: Error[]; skipped?: boolean; canceled?: boolean }>;
6565
+ fragment<TInput extends Record<string, any> = Record<string, any>>(
6566
+ idOrName: string
6567
+ ): ControllerFragmentHandle<TInput>;
6568
+ }
6569
+
6570
+ export type ControllerComputedGetter<
6571
+ TState extends Record<string, any> = Record<string, any>,
6572
+ TResult = any
6573
+ > = (ctx: { state: Readonly<TState>; el: HTMLElement; tasks: Record<string, ClientTask> }) => TResult;
6574
+
6575
+ export type ControllerTaskFactory<
6576
+ TState extends Record<string, any> = Record<string, any>,
6577
+ TData = any
6578
+ > =
6579
+ | ((ctx: ControllerContext<TState>) => ClientTask<TData> | { run: (...args: any[]) => Promise<TData>; concurrency?: ClientConcurrencyPolicy; key?: string })
6580
+ | { run: (...args: any[]) => Promise<TData>; concurrency?: ClientConcurrencyPolicy; key?: string };
6581
+
6582
+ export type ControllerActionHandler<
6583
+ TState extends Record<string, any> = Record<string, any>,
6584
+ TTasks extends Record<string, ClientTask> = Record<string, ClientTask>
6585
+ > = (
6586
+ ctx: ControllerContext<TState, TTasks>,
6587
+ event: Event,
6588
+ actionEl: HTMLElement
6589
+ ) => unknown | Promise<unknown>;
6590
+
6591
+ export interface ControllerDefinition<
6592
+ TState extends Record<string, any> = Record<string, any>,
6593
+ TComputed extends Record<string, ControllerComputedGetter<TState>> = Record<string, ControllerComputedGetter<TState>>,
6594
+ TTasks extends Record<string, ControllerTaskFactory<TState>> = Record<string, ControllerTaskFactory<TState>>
6595
+ > {
6596
+ name?: string;
6597
+ state?: () => TState;
6598
+ computed?: TComputed;
6599
+ tasks?: TTasks;
6600
+ connect?: (
6601
+ ctx: ControllerContext<
6602
+ [TState][TState extends any ? 0 : never] & { readonly [K in keyof TComputed]: ReturnType<TComputed[K]> }
6603
+ >
6604
+ ) => void | (() => void);
6605
+ disconnect?: (
6606
+ ctx: ControllerContext<
6607
+ [TState][TState extends any ? 0 : never] & { readonly [K in keyof TComputed]: ReturnType<TComputed[K]> }
6608
+ >
6609
+ ) => void;
6610
+ actions?: {
6611
+ [actionName: string]: ControllerActionHandler<
6612
+ [TState][TState extends any ? 0 : never] & { readonly [K in keyof TComputed]: ReturnType<TComputed[K]> }
6613
+ >;
6614
+ };
6615
+ }
6616
+
6617
+ export function defineController<
6618
+ TState extends Record<string, any> = Record<string, any>,
6619
+ TComputed extends Record<string, ControllerComputedGetter<TState>> = Record<string, ControllerComputedGetter<TState>>,
6620
+ TTasks extends Record<string, ControllerTaskFactory<TState>> = Record<string, ControllerTaskFactory<TState>>
6621
+ >(
6622
+ definition: ControllerDefinition<TState, TComputed, TTasks>
6623
+ ): ControllerDefinition<TState, TComputed, TTasks> & { __isWebspressoController: true };
6624
+
6625
+ export function deriveControllerNameFromPath(filePath: string): string;
6626
+
6627
+ export interface FragmentLoaderContext<TInput = Record<string, unknown>> {
6628
+ input: TInput;
6629
+ instanceId: string;
6630
+ fragmentName: string;
6631
+ pagePath: string;
6632
+ req: import('express').Request;
6633
+ res: import('express').Response;
6634
+ ctx: PageContext;
6635
+ db: DatabaseInstance | null;
6636
+ user: any;
6637
+ auth: any;
6638
+ params: Record<string, string>;
6639
+ query: Record<string, unknown>;
6640
+ service: PageContext['service'];
6641
+ memo<T>(key: string, factory: () => T | Promise<T>): Promise<T>;
6642
+ }
6643
+
6644
+ export interface FragmentDefinition<TInput = Record<string, unknown>, TData = Record<string, unknown>> {
6645
+ template: string;
6646
+ dependsOn?: string[];
6647
+ schema?: ZodTypeAny | Record<string, ZodTypeAny> | ((helpers: { z: typeof z }) => ZodTypeAny | Record<string, ZodTypeAny>);
6648
+ auth?: boolean | string | string[] | ((user: any, ctx: PageContext) => boolean | Promise<boolean>);
6649
+ middleware?: Array<string | import('express').RequestHandler>;
6650
+ load?: (context: FragmentLoaderContext<TInput>) => TData | Promise<TData>;
6651
+ }
6652
+
6653
+ export function defineFragment<TInput = Record<string, unknown>, TData = Record<string, unknown>>(
6654
+ definition: FragmentDefinition<TInput, TData>
6655
+ ): FragmentDefinition<TInput, TData> & { __isWebspressoFragment: true };
6656
+
6657
+ export interface ApiResultEnvelope<TData = unknown> {
6658
+ readonly __webspressoApiResult: true;
6659
+ readonly data: TData;
6660
+ readonly invalidate: string[];
6661
+ readonly status?: number;
6662
+ readonly headers?: Record<string, string>;
6663
+ }
6664
+
6665
+ export function apiResult<TData = unknown>(
6666
+ data: TData,
6667
+ meta?: {
6668
+ invalidate?: string | string[];
6669
+ status?: number;
6670
+ headers?: Record<string, string>;
6671
+ }
6672
+ ): ApiResultEnvelope<TData>;
6673
+
6674
+ export function isApiResultEnvelope(value: unknown): value is ApiResultEnvelope;
6675
+ export function sendApiResult(req: any, res: any, envelope: ApiResultEnvelope): void;
6676
+ export function createControllerRuntime(options?: Record<string, unknown>): Record<string, any>;
6677
+ export function onTransactionCommit(callback: () => void): void;
6678
+
6679
+ export function createApiClient(options?: Record<string, unknown>): ClientApiClient;
6680
+ export function createFormHandle(formEl: HTMLFormElement, options?: Record<string, unknown>): ClientFormHandle;
6681
+ export function parseFormElement(formEl: HTMLFormElement, options?: Record<string, unknown>): {
6682
+ values: Record<string, unknown>;
6683
+ hasFile: boolean;
6684
+ formData: FormData;
6685
+ };
6686
+ export function createFragmentCoordinator(options?: Record<string, unknown>): Record<string, any>;
6687
+ export function createClientRuntime(options?: Record<string, unknown>): Record<string, any>;
6688
+ export function bootClient(options?: Record<string, unknown>): Record<string, any>;
6689
+ export function createLiteClientRuntime(options?: Record<string, unknown>): Record<string, any>;
6690
+ export function bootLiteClient(options?: Record<string, unknown>): Record<string, any>;
6691
+ export function createDatastarAdapter(options?: Record<string, unknown>): Record<string, any>;
6692
+ export function createClientDebugger(options?: { enabled?: boolean; maxEvents?: number }): Record<string, any>;
6693
+
6694
+ export declare const client: {
6695
+ defineController: typeof defineController;
6696
+ deriveControllerNameFromPath: typeof deriveControllerNameFromPath;
6697
+ createClientRuntime: typeof createClientRuntime;
6698
+ bootClient: typeof bootClient;
6699
+ createLiteClientRuntime: typeof createLiteClientRuntime;
6700
+ bootLiteClient: typeof bootLiteClient;
6701
+ ClientRequestError: typeof ClientRequestError;
6702
+ createApiClient: typeof createApiClient;
6703
+ createFormHandle: typeof createFormHandle;
6704
+ parseFormElement: typeof parseFormElement;
6705
+ createFragmentCoordinator: typeof createFragmentCoordinator;
6706
+ defineFragment: typeof defineFragment;
6707
+ apiResult: typeof apiResult;
6708
+ isApiResultEnvelope: typeof isApiResultEnvelope;
6709
+ createDatastarAdapter: typeof createDatastarAdapter;
6710
+ createClientDebugger: typeof createClientDebugger;
6711
+ [key: string]: any;
6712
+ };